Mercurial > paster

comparison pasterd.8.in @ 14:a5035bcbf7a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: add manual pages
author David Demelier <markand@malikania.fr>
date Thu, 06 Feb 2020 13:24:54 +0100
parents
children 21c103c33ac9
comparison
equal deleted inserted replaced
13:32b063f6bb2c 14:a5035bcbf7a8
1 .\"
2 .\" Copyright (c) 2020 David Demelier <markand@malikania.fr>
3 .\"
4 .\" Permission to use, copy, modify, and/or distribute this software for any
5 .\" purpose with or without fee is hereby granted, provided that the above
6 .\" copyright notice and this permission notice appear in all copies.
7 .\"
8 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15 .\"
16 .Dd 06 February, 2020
17 .Dt PASTERD 8
18 .Os
19 .\" NAME
20 .Sh NAME
21 .Nm pasterd
22 .Nd simple paste service
23 .\" SYNOPSIS
24 .Sh SYNOPSIS
25 .Nm
26 .Op Fl f
27 .Op Fl d Ar database-path
28 .Op Fl t Ar theme-directory
29 .\" DESCRIPTION
30 .Sh DESCRIPTION
31 The
32 .Nm
33 utility is a simple CGI or FastCGI program to host code snippets over a web
34 interface. It will show most recent public pastes and let users to create new
35 one from a web form.
36 .Pp
37 It supports:
38 .Bl -bullet -compat
39 .It
40 Listing of recent pastes,
41 .It
42 Submission of new pastes,
43 .It
44 Language highlighting (depending on the theme),
45 .It
46 Private pastes (not listed).
47 .El
48 .Pp
49 To store pastes,
50 .Nm
51 uses a SQLite database that must be writable by the CGI/FastCGI owner. See usage
52 below.
53 .Pp
54 Available options:
55 .Bl -tag -width Ds
56 .It Fl f
57 Starts as FastCGI mode,
58 .Nm
59 will wait forever for new requests.
60 .It Fl d Ar database-path
61 Specify an alternate path for the database.
62 .It Fl t Ar theme-directory
63 Specify an alternate directory for the theme.
64 .El
65 .\" USAGE
66 .Sh USAGE
67 The
68 .Nm
69 utility does not use configuration file as it does not need many adjustments,
70 instead every parameter could be passed by environment variables or options.
71 .Pp
72 By default,
73 .Nm
74 will try to use
75 .Pa @VARDIR@/paster/paster.db
76 database.
77 .\" USING WITH FASTCGI
78 .Sh USING WITH FASTCGI
79 The recommended way to use
80 .Nm
81 is to deploy using FastCGI. You can use the
82 .Xr kfcgi 8
83 helper to spawn the process for you.
84 .Pp
85 Example:
86 .Bd -literal -offset Ds
87 kfcgi -p /var/www/paster -- pasterd -f -d paster.db -t siimple
88 .Ed
89 .Pp
90 Note: kfcgi chroot to the directory given, you must either statically link
91 pasterd at build time or deploy all required libraries. Also, themes directory
92 will need to be available in the chroot directory. In the above example, this
93 will effectively create a database
94 .Pa /var/www/paster/paster.db
95 and use the theme
96 .Pa /var/www/paster/siimple .
97 .Pp
98 Then, simply copy the desired theme into the directory.
99 .Bd -literal -offset Ds
100 cp -R @SHAREDIR@/paster/themes/siimple /var/www/paster
101 .Ed
102 .Pp
103 As an
104 .Em insecure
105 alternative, you can chroot to
106 .Pa /
107 to avoid static-linking and copying themes, using:
108 .Bd -literal -offset Ds
109 kfcgi -p / -- pasterd -f \e
110 -d /var/www/paster/paster.db \e
111 -t @SHAREDIR@/paster/themes/siimple
112 .Ed
113 .Pp
114 Both kfcgi invocations will create
115 .Pa /var/www/run/http.sock
116 with current user and group. Configure the web server to talk to that socket
117 and make sure it has appropriate file permissions otherwise see
118 .Fl u
119 option in
120 .Nm kfcgi .
121 See also the
122 .Xr kfcgi 8
123 manual for more information.
124 .Pp
125 Next, configure the web server.
126 .Pp
127 Warning: at this moment,
128 .Nm
129 requires its own virtual host and can
130 .Em not
131 use a url.
132 .\" Server: nginx
133 .Ss Server: nginx
134 The nginx web server requires several parameters to run
135 .Nm .
136 .Bd -literal
137 server {
138 server_name mypaste.fr;
139 listen 80;
140
141 location / {
142 fastcgi_param QUERY_STRING query_string;
143 fastcgi_param REQUEST_METHOD $request_method;
144 fastcgi_param CONTENT_TYPE $content_type;
145 fastcgi_param CONTENT_LENGTH $content_length;
146 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
147 fastcgi_param SCRIPT_NAME $fastcgi_script_name;
148 fastcgi_param PATH_INFO $document_uri;
149 fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info;
150 fastcgi_param REQUEST_URI $request_uri;
151 fastcgi_param DOCUMENT_URI $document_uri;
152 fastcgi_param DOCUMENT_ROOT $document_root;
153 fastcgi_param SERVER_PROTOCOL $server_protocol;
154 fastcgi_param GATEWAY_INTERFACE CGI/1.1;
155 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version;
156 fastcgi_param REMOTE_ADDR $remote_addr;
157 fastcgi_param REMOTE_PORT $remote_port;
158 fastcgi_param SERVER_ADDR $server_addr;
159 fastcgi_param SERVER_PORT $server_port;
160 fastcgi_param SERVER_NAME $server_name;
161 fastcgi_param HTTPS $https;
162 fastcgi_pass unix:/var/www/run/httpd.sock;
163 }
164 }
165 .Ed
166 .\" ENVIRONMENT
167 .Sh ENVIRONMENT
168 The following environment variables are detected:
169 .Bl -tag -width Ds
170 .It Va PASTERD_DATABASE_PATH No (string)
171 Path to the SQLite database.
172 .It Va PASTERD_THEME_DIR No (string)
173 Directory containing the theme.
174 .El
175 .\" SEE ALSO
176 .Sh SEE ALSO
177 .Xr paster 8 ,
178 .Xr kfcgi 8