From 21d51f7e0a639a3224ffc45dc3c06854decf1d45 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Tue, 30 Jan 2024 20:51:38 +0000 Subject: Initial commit Signed-off-by: Laurent Bercot --- doc/apasted.html | 137 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 doc/apasted.html (limited to 'doc/apasted.html') 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 @@ + + + + + + apaste: the apasted program + + + + + + +

+apaste
+Software
+skarnet.org +

+ +

The `apasted` program

+ +

+ apasted 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 apastec client. It reads a +series of files transmitted by the client, stores it on the server, and +sends back a slug to the client, i.e. an identifier for the +stored files. +

+ +

Interface

+ +

+     apasted [ -r rtimeout ] [ -w wtimeout ] [ -d rootdir ] [ -p prefix ] [ -m maxfiles ]
+

+ +

apasted reads data on its stdin, expecting the protocol spoken by the +apastec client, containing one or more files.
It creates a subdirectory subdir in its working directory, +and stores the files it receives under it. +
- If it only receives one file, it stores it in subdir/index.txt.
- If it receives two or more files, it stores each file file as +subdir/file.txt, and creates a +subdir/index.html file with hyperlinks to every file in subdir.
It sends the subdir name back to the client, as a slug.
It exits 0

+ +

Exit codes

+ +

0: Success.
1: Protocol error. The client sent incorrectly formatted data.
100: Bad usage. apasted was run in an incorrect way.
111: System call failed. This usually signals an issue with the +underlying operating system, or with the network in some way. +

+ +

Options

+ +

-r rtimeout: If the client hasn't transmitted all its data within rtimeout +milliseconds, give up. The default is 0, meaning infinite: apasted will +wait forever for client data if necessary.
-w wtimeout: If apasted fails to send the slug to the client within wtimeout +milliseconds, give up. The default is 0, meaning infinite: apasted will +take as much time as it needs to send its answer.
-d rootdir: Switch to rootdir and store files there. The default is +apasted's working directory.
-p prefix: When sending a slug to the client, prefix subdir with prefix, +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 prefix +is the URL of apasted's base directory, then the slug can directly be used as a +URL to access the client's files.
-m maxfiles: Accept a maximum of maxfiles 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.

+ +

Typical usage

+ +

apasted is meant to be run under a super-server accepting client connections. +Run it under inetd or +s6-tcpserver +for plaintext connections, and under +s6-tlsserver +for TLS-tunneled connections.
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 +-p option on the apasted command line to make sure the client receives +a full URL to its files.

+ +

Caveats

+ +

apaste is a push 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: +
- If possible, have quotas on the filesystem hosting the apasted storage area
- Use the -m option to avoid trivial inode exhaustion attacks
- Use your super-server's options to mitigate client patterns of abuse, log and +block the IPs of problematic clients
- Run scripts that regularly delete old subdirs (and their contents) +in the apasted storage area.
- 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.

+ +

Notes

+ +

apasted will store a file named file as file.txt 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.
A unique file is stored as slug/index.txt; if apasted is +run with -p http://example.com/ then the apaste client, on success, +will print http://example.com/slug/. Make sure that your web server can +automatically interpret that URL as http://example.com/slug/index.txt.

+ + + -- cgit v1.3.1