Mercurial > paster
annotate pasterd.8.in @ 25:f4e8a7920b94
pasterd: implement search, closes #2474 @30m
author | David Demelier <markand@malikania.fr> |
---|---|
date | Fri, 07 Feb 2020 13:23:48 +0100 |
parents | 21c103c33ac9 |
children | a47801a1522a |
rev | line source |
---|---|
14 | 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 | |
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
26 .Op Fl fqv |
14 | 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. | |
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
64 .It Fl q |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
65 Do not log through syslog at all. |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
66 .It Fl v |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
67 Increase verbosity level. |
14 | 68 .El |
69 .\" USAGE | |
70 .Sh USAGE | |
71 The | |
72 .Nm | |
73 utility does not use configuration file as it does not need many adjustments, | |
74 instead every parameter could be passed by environment variables or options. | |
75 .Pp | |
76 By default, | |
77 .Nm | |
78 will try to use | |
79 .Pa @VARDIR@/paster/paster.db | |
80 database. | |
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
81 .\" LOGS |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
82 .Sh LOGS |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
83 The |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
84 .Nm |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
85 utility will log information through syslog unless verbosity is disabled. |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
86 Except at startup where the tool can write to stderr some information if it |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
87 can't continue processing, the tool will never write anything to stdout and |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
88 use syslog only. |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
89 .Pp |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
90 The available verbosity level is defined in the following order: |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
91 .Bd -literal -offset Ds |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
92 none < warnings (default) < info < debug |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
93 .Ed |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
94 .Pp |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
95 Use |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
96 .Fl q |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
97 or |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
98 .Va PASTERD_VERBOSITY=0 |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
99 if you want to disable syslog completely. |
14 | 100 .\" USING WITH FASTCGI |
101 .Sh USING WITH FASTCGI | |
102 The recommended way to use | |
103 .Nm | |
104 is to deploy using FastCGI. You can use the | |
105 .Xr kfcgi 8 | |
106 helper to spawn the process for you. | |
107 .Pp | |
108 Example: | |
109 .Bd -literal -offset Ds | |
110 kfcgi -p /var/www/paster -- pasterd -f -d paster.db -t siimple | |
111 .Ed | |
112 .Pp | |
113 Note: kfcgi chroot to the directory given, you must either statically link | |
114 pasterd at build time or deploy all required libraries. Also, themes directory | |
115 will need to be available in the chroot directory. In the above example, this | |
116 will effectively create a database | |
117 .Pa /var/www/paster/paster.db | |
118 and use the theme | |
119 .Pa /var/www/paster/siimple . | |
120 .Pp | |
121 Then, simply copy the desired theme into the directory. | |
122 .Bd -literal -offset Ds | |
123 cp -R @SHAREDIR@/paster/themes/siimple /var/www/paster | |
124 .Ed | |
125 .Pp | |
126 As an | |
127 .Em insecure | |
128 alternative, you can chroot to | |
129 .Pa / | |
130 to avoid static-linking and copying themes, using: | |
131 .Bd -literal -offset Ds | |
132 kfcgi -p / -- pasterd -f \e | |
133 -d /var/www/paster/paster.db \e | |
134 -t @SHAREDIR@/paster/themes/siimple | |
135 .Ed | |
136 .Pp | |
137 Both kfcgi invocations will create | |
138 .Pa /var/www/run/http.sock | |
139 with current user and group. Configure the web server to talk to that socket | |
140 and make sure it has appropriate file permissions otherwise see | |
141 .Fl u | |
142 option in | |
143 .Nm kfcgi . | |
144 See also the | |
145 .Xr kfcgi 8 | |
146 manual for more information. | |
147 .Pp | |
148 Next, configure the web server. | |
149 .Pp | |
150 Warning: at this moment, | |
151 .Nm | |
152 requires its own virtual host and can | |
153 .Em not | |
154 use a url. | |
155 .\" Server: nginx | |
156 .Ss Server: nginx | |
157 The nginx web server requires several parameters to run | |
158 .Nm . | |
159 .Bd -literal | |
160 server { | |
161 server_name mypaste.fr; | |
162 listen 80; | |
163 | |
164 location / { | |
165 fastcgi_param QUERY_STRING query_string; | |
166 fastcgi_param REQUEST_METHOD $request_method; | |
167 fastcgi_param CONTENT_TYPE $content_type; | |
168 fastcgi_param CONTENT_LENGTH $content_length; | |
169 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; | |
170 fastcgi_param SCRIPT_NAME $fastcgi_script_name; | |
171 fastcgi_param PATH_INFO $document_uri; | |
172 fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; | |
173 fastcgi_param REQUEST_URI $request_uri; | |
174 fastcgi_param DOCUMENT_URI $document_uri; | |
175 fastcgi_param DOCUMENT_ROOT $document_root; | |
176 fastcgi_param SERVER_PROTOCOL $server_protocol; | |
177 fastcgi_param GATEWAY_INTERFACE CGI/1.1; | |
178 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; | |
179 fastcgi_param REMOTE_ADDR $remote_addr; | |
180 fastcgi_param REMOTE_PORT $remote_port; | |
181 fastcgi_param SERVER_ADDR $server_addr; | |
182 fastcgi_param SERVER_PORT $server_port; | |
183 fastcgi_param SERVER_NAME $server_name; | |
184 fastcgi_param HTTPS $https; | |
185 fastcgi_pass unix:/var/www/run/httpd.sock; | |
186 } | |
187 } | |
188 .Ed | |
189 .\" ENVIRONMENT | |
190 .Sh ENVIRONMENT | |
191 The following environment variables are detected: | |
192 .Bl -tag -width Ds | |
193 .It Va PASTERD_DATABASE_PATH No (string) | |
194 Path to the SQLite database. | |
195 .It Va PASTERD_THEME_DIR No (string) | |
196 Directory containing the theme. | |
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
197 .It Va PASTERD_VERBOSITY No (number) |
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
198 Verbosity level, 0 to disable completely. |
14 | 199 .El |
200 .\" SEE ALSO | |
201 .Sh SEE ALSO | |
202 .Xr paster 8 , | |
203 .Xr kfcgi 8 |