# HG changeset patch # User David Demelier # Date 1580991894 -3600 # Node ID a5035bcbf7a823bf0e4ca541c0644dd9670ef0a2 # Parent 32b063f6bb2c1f2a1086a4748da56041cb4dc4f0 doc: add manual pages diff -r 32b063f6bb2c -r a5035bcbf7a8 .hgignore --- a/.hgignore Thu Feb 06 10:40:32 2020 +0100 +++ b/.hgignore Thu Feb 06 13:24:54 2020 +0100 @@ -20,5 +20,5 @@ \.d$ # Executables. -pasterd -paster +^pasterd(\.8)?$ +^paster(\.1)?$ diff -r 32b063f6bb2c -r a5035bcbf7a8 Makefile --- a/Makefile Thu Feb 06 10:40:32 2020 +0100 +++ b/Makefile Thu Feb 06 13:24:54 2020 +0100 @@ -34,12 +34,13 @@ PREFIX= /usr/local BINDIR= ${PREFIX}/bin SHAREDIR= ${PREFIX}/share +MANDIR= ${PREFIX}/share/man VARDIR= ${PREFIX}/var DEFINES= -DSHAREDIR=\"${SHAREDIR}\" -DVARDIR=\"${VARDIR}\" .SUFFIXES: -.SUFFIXES: .c .o +.SUFFIXES: .c .o .in all: pasterd paster @@ -48,16 +49,21 @@ .c.o: ${CC} ${CFLAGS} ${DEFINES} -MMD -Iextern -c $< +.in: + sed -e "s|@SHAREDIR@|${SHAREDIR}|" \ + -e "s|@VARDIR@|${VARDIR}|" \ + < $< > $@ + extern/sqlite3.o: extern/sqlite3.c extern/sqlite3.h ${CC} ${CFLAGS} ${SQLITE_FLAGS} -MMD -c $< -o $@ extern/libsqlite3.a: extern/sqlite3.o ${AR} -rc $@ $< -pasterd: ${OBJS} extern/libsqlite3.a +pasterd: ${OBJS} extern/libsqlite3.a paster.8 ${CC} -o $@ ${OBJS} ${LDFLAGS} extern/libsqlite3.a -paster: paster.sh +paster: paster.sh paster.1 cp paster.sh paster chmod +x paster @@ -68,12 +74,14 @@ install-paster: mkdir -p ${DESTDIR}${BINDIR} cp paster ${DESTDIR}${BINDIR} + cp paster.1 ${DESTDIR}${MANDIR}/man1/paster.1 install-pasterd: mkdir -p ${DESTDIR}${BINDIR} cp pasterd ${DESTDIR}${BINDIR} mkdir -p ${DESTDIR}${SHAREDIR}/paster cp -R themes ${DESTDIR}${SHAREDIR}/paster + cp pasterd.8 ${DESTDIR}${MANDIR}/man8/pasterd.8 install: install-pasterd install-paster diff -r 32b063f6bb2c -r a5035bcbf7a8 paster.1.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/paster.1.in Thu Feb 06 13:24:54 2020 +0100 @@ -0,0 +1,91 @@ +.\" +.\" Copyright (c) 2020 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd 06 February, 2020 +.Dt PASTER 1 +.Os +.\" NAME +.Sh NAME +.Nm paster +.Nd simple paste service client +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm +.Op Fl LDvx +.Op Fl a Ar author +.Op Fl l Ar language +.Op Fl d Ar duration +.Op Fl t Ar title +.Ar filename +.Ar host +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +tool is the convenient brother to +.Nm pasterd , +it will paste some content into an instance. +.Pp +The +.Ar filename +argument can points to a file whose content will be pasted, if it is set to +.Dq - +then standard input is read instead. +.Pp +The +.Ar host +argument is a URL where a +.Nm pasterd +instance is running. +.Pp +Available options: +.Bl -tag -width Ds +.It Fl L +List all supported languages. +.It Fl D +List all supported durations. +.It Fl v +Be more verbose. +.It Fl x +Store the paste as private. +.It Fl a Ar author +Sets the author, defaults to +.Dq Anonymous . +.It Fl l Ar language +Sets the code snippet language, defaults to +.Dq "nohighlight" . +.It Fl d Ar duration +Sets the paste lifetime, defaults to +.Dq "month" . +.It Fl t Ar title +Sets a title to the paste, defaults to +.Dq "Untitled" . +.\" EXAMPLES +.Sh EXAMPLES +.Ss Paste the main.sh script shell with a title and an author. +.Bd -literal -offset +paster -t "Some shell script" -a Francis -l shell main.sh http://example.org +.Ed +.Ss Read standard input and paste it. +.Bd -literal -offset +grep error logs.txt | paster - http://example.org +.Ed +.Ss Paste a non-listed file with a short duration. +.Bd -literal -offset +paste -x -d hour private.txt http://example.org +.Ed +.\" SEE ALSO +.Sh SEE ALSO +.Xr pasterd 8 diff -r 32b063f6bb2c -r a5035bcbf7a8 pasterd.8.in --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pasterd.8.in Thu Feb 06 13:24:54 2020 +0100 @@ -0,0 +1,178 @@ +.\" +.\" Copyright (c) 2020 David Demelier +.\" +.\" Permission to use, copy, modify, and/or distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd 06 February, 2020 +.Dt PASTERD 8 +.Os +.\" NAME +.Sh NAME +.Nm pasterd +.Nd simple paste service +.\" SYNOPSIS +.Sh SYNOPSIS +.Nm +.Op Fl f +.Op Fl d Ar database-path +.Op Fl t Ar theme-directory +.\" DESCRIPTION +.Sh DESCRIPTION +The +.Nm +utility is a simple CGI or FastCGI program to host code snippets over a web +interface. It will show most recent public pastes and let users to create new +one from a web form. +.Pp +It supports: +.Bl -bullet -compat +.It +Listing of recent pastes, +.It +Submission of new pastes, +.It +Language highlighting (depending on the theme), +.It +Private pastes (not listed). +.El +.Pp +To store pastes, +.Nm +uses a SQLite database that must be writable by the CGI/FastCGI owner. See usage +below. +.Pp +Available options: +.Bl -tag -width Ds +.It Fl f +Starts as FastCGI mode, +.Nm +will wait forever for new requests. +.It Fl d Ar database-path +Specify an alternate path for the database. +.It Fl t Ar theme-directory +Specify an alternate directory for the theme. +.El +.\" USAGE +.Sh USAGE +The +.Nm +utility does not use configuration file as it does not need many adjustments, +instead every parameter could be passed by environment variables or options. +.Pp +By default, +.Nm +will try to use +.Pa @VARDIR@/paster/paster.db +database. +.\" USING WITH FASTCGI +.Sh USING WITH FASTCGI +The recommended way to use +.Nm +is to deploy using FastCGI. You can use the +.Xr kfcgi 8 +helper to spawn the process for you. +.Pp +Example: +.Bd -literal -offset Ds +kfcgi -p /var/www/paster -- pasterd -f -d paster.db -t siimple +.Ed +.Pp +Note: kfcgi chroot to the directory given, you must either statically link +pasterd at build time or deploy all required libraries. Also, themes directory +will need to be available in the chroot directory. In the above example, this +will effectively create a database +.Pa /var/www/paster/paster.db +and use the theme +.Pa /var/www/paster/siimple . +.Pp +Then, simply copy the desired theme into the directory. +.Bd -literal -offset Ds +cp -R @SHAREDIR@/paster/themes/siimple /var/www/paster +.Ed +.Pp +As an +.Em insecure +alternative, you can chroot to +.Pa / +to avoid static-linking and copying themes, using: +.Bd -literal -offset Ds +kfcgi -p / -- pasterd -f \e + -d /var/www/paster/paster.db \e + -t @SHAREDIR@/paster/themes/siimple +.Ed +.Pp +Both kfcgi invocations will create +.Pa /var/www/run/http.sock +with current user and group. Configure the web server to talk to that socket +and make sure it has appropriate file permissions otherwise see +.Fl u +option in +.Nm kfcgi . +See also the +.Xr kfcgi 8 +manual for more information. +.Pp +Next, configure the web server. +.Pp +Warning: at this moment, +.Nm +requires its own virtual host and can +.Em not +use a url. +.\" Server: nginx +.Ss Server: nginx +The nginx web server requires several parameters to run +.Nm . +.Bd -literal +server { + server_name mypaste.fr; + listen 80; + + location / { + fastcgi_param QUERY_STRING query_string; + fastcgi_param REQUEST_METHOD $request_method; + fastcgi_param CONTENT_TYPE $content_type; + fastcgi_param CONTENT_LENGTH $content_length; + fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; + fastcgi_param SCRIPT_NAME $fastcgi_script_name; + fastcgi_param PATH_INFO $document_uri; + fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; + fastcgi_param REQUEST_URI $request_uri; + fastcgi_param DOCUMENT_URI $document_uri; + fastcgi_param DOCUMENT_ROOT $document_root; + fastcgi_param SERVER_PROTOCOL $server_protocol; + fastcgi_param GATEWAY_INTERFACE CGI/1.1; + fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; + fastcgi_param REMOTE_ADDR $remote_addr; + fastcgi_param REMOTE_PORT $remote_port; + fastcgi_param SERVER_ADDR $server_addr; + fastcgi_param SERVER_PORT $server_port; + fastcgi_param SERVER_NAME $server_name; + fastcgi_param HTTPS $https; + fastcgi_pass unix:/var/www/run/httpd.sock; + } +} +.Ed +.\" ENVIRONMENT +.Sh ENVIRONMENT +The following environment variables are detected: +.Bl -tag -width Ds +.It Va PASTERD_DATABASE_PATH No (string) +Path to the SQLite database. +.It Va PASTERD_THEME_DIR No (string) +Directory containing the theme. +.El +.\" SEE ALSO +.Sh SEE ALSO +.Xr paster 8 , +.Xr kfcgi 8