1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>apaste: the apasted program</title>
<meta name="Description" content="apaste: the apasted program" />
<meta name="Keywords" content="apasted apaste server pastebin command-line tpaste sprunge fiche" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="index.html">apaste</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>apasted</tt> program </h1>
<p>
<tt>apasted</tt> is the server-side program for the apaste package. It
expects its stdin and stdout to be connected to the network, having being
contacted by an <a href="apastec.html">apastec</a> client. It reads a
series of files transmitted by the client, stores it on the server, and
sends back a <em>slug</em> to the client, i.e. an identifier for the
stored files.
</p>
<h2> Interface </h2>
<pre>
apasted [ -r <em>rtimeout</em> ] [ -w <em>wtimeout</em> ] [ -d <em>rootdir</em> ] [ -p <em>prefix</em> ] [ -n <em>maxfiles</em> ] [ -s <em>maxsize</em> ] [ -S <em>maxtotalsize</em> ]
</pre>
<ul>
<li> apasted reads data on its stdin, expecting the protocol spoken by the
<a href="apastec.html">apastec</a> client, containing one or more files. </li>
<li> It creates a subdirectory <em>subdir</em> in its working directory,
and stores the files it receives under it.
<ul>
<li> If it only receives one file, it stores it in <tt><em>subdir</em>/index.txt</tt>. </li>
<li> If it receives two or more files, it stores each file <em>file</em> as
<tt><em>subdir</em>/<em>file</em>.txt</tt>, and creates a
<tt><em>subdir</em>/index.html</tt> file with hyperlinks to every file in <em>subdir</em>. </li>
</ul> </li>
<li> It sends the <em>subdir</em> name back to the client, as a <em>slug</em>. </li>
<li> It exits 0 </li>
</ul>
<h2> Exit codes </h2>
<dl>
<dt> 0 </dt> <dd> Success. </dd>
<dt> 1 </dt> <dd> Protocol error. The client sent incorrectly formatted data. </dd>
<dt> 100 </dt> <dd> Bad usage. apasted was run in an incorrect way. </dd>
<dt> 111 </dt> <dd> System call failed. This usually signals an issue with the
underlying operating system, or with the network in some way. </dt>
</dl>
<h2> Options </h2>
<dl>
<dt> -r <em>rtimeout</em> </dt>
<dd> If the client hasn't transmitted all its data within <em>rtimeout</em>
milliseconds, give up. The default is 0, meaning infinite: apasted will
wait forever for client data if necessary. </dd>
<dt> -w <em>wtimeout</em> </dt>
<dd> If apasted fails to send the slug to the client within <em>wtimeout</em>
milliseconds, give up. The default is 0, meaning infinite: apasted will
take as much time as it needs to send its answer. </dd>
<dt> -d <em>rootdir</em> </dt>
<dd> Switch to <em>rootdir</em> and store files there. The default is
apasted's working directory. </dd>
<dt> -p <em>prefix</em> </dt>
<dd> When sending a slug to the client, prefix <em>subdir</em> with <em>prefix</em>,
and append a slash at the end if <em>prefix</em> starts with <tt>http</tt>.
This is useful when apasted writes its files to
a web server's document hierarchy, which is the intended case. If <em>prefix</em>
is the URL of apasted's base directory, then the slug can directly be used as a
URL to access the client's files. </dd>
<dt> -n <em>maxfiles</em> </dt>
<dd> Accept a maximum of <em>maxfiles</em> files at a time from the client.
The default is 0, meaning unlimited: the client can send as many files as it
wants and apasted will still store them if it is possible. </dd>
<dt> -s <em>maxsize</em> </dt>
<dd> Accept a maximum of <em>maxsize</em> bytes for each file.
0 means unlimited: the files can be as big as the client
wants, which is not a very good idea. The default is 1 MB. </dd>
<dt> -S <em>maxtotalsize</em> </dt>
<dd> Accept a maximum of <em>maxtotalsize</em> bytes for a single
apaste transaction, all files included.
0 means unlimited: the transaction can be as large as the client
wants, which is not a very good idea. The default is 10 MB. </dd>
</dl>
<h2> Typical usage </h2>
<ul>
<li> apasted is meant to be run under a super-server accepting client connections.
Run it under inetd or
<a href="//skarnet.org/software/s6-networking/s6-tcpserver.html">s6-tcpserver</a>
for plaintext connections, and under
<a href="//skarnet.org/software/s6-networking/s6-tlsserver.html">s6-tlsserver</a>
for TLS-tunneled connections. </li>
<li> To publish the data received and stored by apasted, the simplest way is
to have a web server running and serving the hierarchy of apasted files. Use the
<tt>-p</tt> option on the apasted command line to make sure the client receives
a full URL to its files. </li>
</ul>
<h2> Caveats </h2>
<ul>
<li> apaste is a <em>push</em> protocol: the client sends data to be stored on
the server. As such, it is very easy to abuse, and caution should be taken when
running an apasted server:
<ul>
<li> If possible, have quotas on the filesystem hosting the apasted storage area </li>
<li> Use the <tt>-n</tt> option to avoid trivial inode exhaustion attacks </li>
<li> Use your super-server's options to mitigate client patterns of abuse, log and
block the IPs of problematic clients </li>
<li> Run scripts that regularly delete old <em>subdir</em>s (and their contents)
in the apasted storage area. </li>
<li> Be aware, and warn your users, that a pastebin is a service to the community,
and that abusing the service is the best and quickest way to make it go away. </li>
</ul> </li>
</ul>
<h2> Notes </h2>
<ul>
<li> apasted will store a file named <em>file</em> as <em>file.txt</em> so that a
web server can always serve it as plain text. apaste is not meant to send binary
files of an arbitrary MIME type. </li>
<li> A unique file is stored as <tt><em>slug</em>/index.txt</tt>; if apasted is
run with <tt>-p http://example.com/</tt> then the apaste client, on success,
will print <tt>http://example.com/<em>slug</em>/</tt>. Make sure that your web server can
automatically interpret that URL as <tt>http://example.com/<em>slug</em>/index.txt</tt>. </li>
</ul>
</body>
</html>
|
