Initial commit

Signed-off-by: Laurent Bercot <ska@appnovation.com>
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
download: apaste-21d51f7e0a639a3224ffc45dc3c06854decf1d45.tar.gz
5 files changed, 477 insertions, 0 deletions
diff --git a/doc/apaste.html b/doc/apaste.html
new file mode 100644
index 0000000..34f66d3
--- /dev/null
+++ b/doc/apaste.html
@@ -0,0 +1,114 @@
+<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 apaste program</title>
+    <meta name="Description" content="apaste: the apaste program" />
+    <meta name="Keywords" content="apaste client interface pastebin command-line tpaste sprunge fiche s6-networking tcpclient tlsclient tls ssl" />
+    <!-- <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>apaste</tt> program </h1>
+
+<p>
+ <tt>apaste</tt> is a program that reads one or more files, or its
+standard input, and sends the data to an <a href="apasted.html">apasted</a>
+server.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     apaste [ -S | -s ] [ -C <em>cadir</em> ] [ -d <em>server</em>[<em>:port</em>] ] [ -r <em>rtimeout</em> ] [ -w <em>wtimeout</em> ] <em>file...</em>
+</pre>
+
+<ul>
+ <li> apaste connects to a remote server via a plaintext or TLS-secured
+connection, expecting to find an <a href="apasted.html">apasted</a> server at the
+other end. </li>
+ <li> For every <em>file</em> given as argument, it sends the contents of <em>file</em>
+over the network. If <em>file</em> is <tt>-</tt> (dash), then stdout is transmitted
+until EOF. </li>
+ <li> The server answers with a blob of six printable characters, named a <em>slug</em>.
+Depending on the server configuration, it may embed the slug in a complete URL, for
+easy copy-paste into a browser; or it may embed it in another way. </li>
+ <li> apaste prints the slug to its stdout, then exits 0. </li>
+</ul>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. The data has been recorded by the server and available in
+some way as indicated by the slug. </dd>
+ <dt> 100 </dt> <dd> Bad usage. apaste 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> -S </dt>
+ <dd> Normal, plain text connection to the server, even if the built-in default
+is TLS. The built-in default can be changed via the <tt>--with-default-tls</tt>
+or <tt>--without-default-tls</tt> options to configure. </dd>
+
+ <dt> -s </dt>
+ <dd> TLS connection to the server, even if the built-in default
+is plain text. The built-in default can be changed via the <tt>--with-default-tls</tt>
+or <tt>--without-default-tls</tt> options to configure. </dd>
+
+ <dt> -C <em>cadir</em> </dt>
+ <dd> When using a TLS connection, use <em>cadir</em> as the directory
+containing the hashed names of the trust anchor certificates
+(used for verifying the server's certificate chain). The built-in default
+can be changed via the <tt>--with-default-cadir</tt> option to configure. </dd>
+
+ <dt> -d <em>server</em>[<em>:port</em>] </dt>
+ <dd> Connect to server <em>server</em>, port <em>port</em>. The built-in defaults
+can be changed via the <tt>--with-default-server</tt>, <tt>--with-default-port</tt>,
+and <tt>--with-default-tlsport</tt> options to configure. </dd>
+
+ <dt> -r <em>rtimeout</em> </dt>
+ <dd> If the server isn't answering with a slug within <em>rtimeout</em>
+milliseconds, give up. The default is 0, meaning infinite: apaste will
+wait forever for a server reply if necessary. </dd>
+
+ <dt> -w <em>wtimeout</em> </dt>
+ <dd> If the server hasn't accepted all the data within <em>wtimeout</em>
+milliseconds, give up. The default is 0, meaning infinite: apaste will
+take as much time as it needs to send its data. </dd>
+</dl>
+
+<h2> Example usage </h2>
+
+<ul>
+ <li> <code>$ echo Blah blah. | apaste -</code> </li>
+ <li> <code># apaste /etc/shadow   </code> <small>(Just kidding. Don't do that.)</small> </li>
+</ul>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> apaste is only a wrapper around
+<a href="//skarnet.org/software/s6-networking/s6-tcpclient.html">s6-tcpclient</a>
+(for plain connections) or
+<a href="//skarnet.org/software/s6-networking/s6-tlsclient.html">s6-tlsclient</a>
+(for TLS-tunneled connections), and
+<a href="apastec.html">apastec</a> that is the real client. The point of apaste
+is to provide a short command line with good compiled-in defaults; make sure
+your defaults are correct at configure time when building the apaste package. </li>
+ <li> <tt>-</tt>, i.e. stdin, cannot be mentioned several times as an argument. It
+can be transmitted with other files, but cannot be duplicated. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/apastec.html b/doc/apastec.html
new file mode 100644
index 0000000..6711f3f
--- /dev/null
+++ b/doc/apastec.html
@@ -0,0 +1,88 @@
+<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 apastec program</title>
+    <meta name="Description" content="apaste: the apastec program" />
+    <meta name="Keywords" content="apastec apaste client interface 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>apastec</tt> program </h1>
+
+<p>
+ <tt>apastec</tt> is a program that reads one or more files, or its
+standard input, and sends them to a preopened file descriptor.
+</p>
+
+<h2> Interface </h2>
+
+<pre>
+     apastec [ -r <em>rtimeout</em> ] [ -w <em>wtimeout</em> ] <em>file...</em>
+</pre>
+
+<ul>
+ <li> apastec expects to have, in addition to standard file descriptors 0, 1 and 2,
+its file descriptors 6 and 7 open and connected to a remote
+<a href="apasted.html">apasted</a> server. </li>
+ <li> For every <em>file</em> given as argument, it sends the contents of <em>file</em>
+over the network. If <em>file</em> is <tt>-</tt> (dash), then stdout is transmitted
+until EOF. </li>
+ <li> The server answers with a blob of six printable characters, named a <em>slug</em>.
+Depending on the server configuration, it may embed the slug in a complete URL, for
+easy copy-paste into a browser; or it may embed it in another way. </li>
+ <li> apastec prints the slug to its stdout, then exits 0. </li>
+</ul>
+
+<h2> Exit codes </h2>
+
+<dl>
+ <dt> 0 </dt> <dd> Success. The data has been recorded by the server and available in
+some way as indicated by the slug. </dd>
+ <dt> 100 </dt> <dd> Bad usage. apaste 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 server isn't answering with a slug within <em>rtimeout</em>
+milliseconds, give up. The default is 0, meaning infinite: apastec will
+wait forever for a server reply if necessary. </dd>
+
+ <dt> -w <em>wtimeout</em> </dt>
+ <dd> If the server hasn't accepted all the data within <em>wtimeout</em>
+milliseconds, give up. The default is 0, meaning infinite: apastec will
+take as much time as it needs to send its data. </dd>
+</dl>
+
+<h2> Typical usage </h2>
+
+<p>
+ apastec isn't meant to be used directly. It is meant to be invoked as
+part of a command line crafted by the <a href="apaste.html">apaste</a>
+command, where programs from the
+<a href="//skarnet.org/software/s6-networking/">s6-networking</a> package
+establish the connection to the server, then exec into apastec to read
+the user's data and transmit them with the apaste protocol.
+</p>
+
+<h2> Notes </h2>
+
+<ul>
+ <li> <tt>-</tt>, i.e. stdin, cannot be mentioned several times as an argument. It
+can be transmitted with other files, but cannot be duplicated. </li>
+</ul>
+
+</body>
+</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 @@
+<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>
diff --git a/doc/index.html b/doc/index.html
new file mode 100644
index 0000000..6697333
--- /dev/null
+++ b/doc/index.html
@@ -0,0 +1,110 @@
+<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 - a small command-line pastebin</title>
+    <meta name="Description" content="apaste - a small command-line pastebin" />
+    <meta name="Keywords" content="apaste pastebin tpaste fiche command line laurent bercot ska skarnet" />
+    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> apaste </h1>
+
+<h2> What is it&nbsp;? </h2>
+
+<p>
+  apaste is a small command-line pastebin, to share terminal output
+by pushing it to a server, so it can be made public via the Web or some
+other protocol.
+</p>
+
+<hr />
+
+<h2> Installation </h2>
+
+<h3> Requirements </h3>
+
+<ul>
+ <li> A POSIX-compliant system with a standard C development environment </li>
+ <li> GNU make, version 3.81 or later </li>
+ <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> version
+2.14.1.1 or later. It's a build-time requirement. It's also a run-time
+requirement if you link against the shared version of the skalibs
+library. </li>
+ <li> <a href="//skarnet.org/software/s6-networking/">s6-networking</a> version
+2.7.0.2 or later. It's a build-time and run-time requirement: it's the layer
+that provides the network connection. </li>
+</ul>
+
+<h3> Licensing </h3>
+
+<p>
+ apaste is free software. It is available under the
+<a href="https://opensource.org/licenses/ISC">ISC license</a>.
+</p>
+
+<h3> Download </h3>
+
+<ul>
+ <li> The current released version of apaste is
+<a href="apaste-0.0.1.0.tar.gz">0.0.1.0</a>. </li>
+ <li> You can checkout a copy of the
+<a href="//git.skarnet.org/cgi-bin/cgit.cgi/apaste/">apaste
+git repository</a>:
+<pre> git clone git://git.skarnet.org/apaste </pre> </li>
+ <li> There's also a
+<a href="https://github.com/skarnet/apaste">GitHub mirror</a>
+of the apaste git repository. </li>
+</ul>
+
+<h3> Compilation </h3>
+
+<ul>
+ <li> See the enclosed INSTALL file for installation details. </li>
+</ul>
+
+<h3> Upgrade notes </h3>
+
+<ul>
+ <li> <a href="upgrade.html">This page</a> lists the differences to be aware of between
+the previous versions of apaste and the current one. </li>
+</ul>
+
+<hr />
+
+<h2> Reference </h2>
+
+<h3> Commands </h3>
+
+<ul>
+ <li> <a href="apaste.html">The <tt>apaste</tt> program</a> </li>
+ <li> <a href="apastec.html">The <tt>apastec</tt> program</a> </li>
+ <li> <a href="apasted.html">The <tt>apasted</tt> program</a> </li>
+</ul>
+
+<h2> Related resources </h2>
+
+<ul>
+ <li> <tt>apaste</tt> is discussed on the
+<a href="//skarnet.org/lists/#skaware">skaware</a> mailing-list. </li>
+</ul>
+
+<h2> Similar work </h2>
+
+<ul>
+ <li> <a href="https://github.com/solusipse/fiche">fiche</a> is also
+a small command-line pastebin utility. </li>
+ <li> <a href="https://tpaste.us/">tpaste</a> and
+<a href="https://sprunge.us/">sprunge </a> are similar utilities,
+one written in lua, the other in Python. </li>
+</ul>
+
+</body>
+</html>
diff --git a/doc/upgrade.html b/doc/upgrade.html
new file mode 100644
index 0000000..c8650e5
--- /dev/null
+++ b/doc/upgrade.html
@@ -0,0 +1,28 @@
+<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: how to upgrade</title>
+    <meta name="Description" content="apaste: how to upgrade" />
+    <meta name="Keywords" content="apaste installation upgrade" />
+    <!-- <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> What has changed in apaste </h1>
+
+<h2> in 0.0.1.0 </h2>
+
+<ul>
+ <li> Initial release. </li>
+</ul>
+
+</body>
+</html>
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
download	apaste-21d51f7e0a639a3224ffc45dc3c06854decf1d45.tar.gz