diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2024-01-30 20:51:38 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2024-01-30 20:51:38 +0000 |
| commit | 21d51f7e0a639a3224ffc45dc3c06854decf1d45 (patch) | |
| tree | 87c4a36f66510e79d7ec8315361bb8bbbb5767f5 /doc/apasted.html | |
| download | apaste-21d51f7e0a639a3224ffc45dc3c06854decf1d45.tar.gz | |
Initial commit
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat (limited to 'doc/apasted.html')
| -rw-r--r-- | doc/apasted.html | 137 |
1 files changed, 137 insertions, 0 deletions
diff --git a/doc/apasted.html b/doc/apasted.html new file mode 100644 index 0000000..98ec51d --- /dev/null +++ b/doc/apasted.html @@ -0,0 +1,137 @@ +<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> ] [ -m <em>maxfiles</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. 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> -m <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> +</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>-m</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> |