Mercurial > paster
annotate pasterd.8 @ 78:9bfe5ce3cc45
pasterd: rework themes
| author | David Demelier <markand@malikania.fr> |
|---|---|
| date | Thu, 16 Mar 2023 20:45:59 +0100 |
| parents | 67b3d13a5035 |
| children |
| rev | line source |
|---|---|
| 14 | 1 .\" |
|
72
1a98bc0daa49
misc: update copyright years
David Demelier <markand@malikania.fr>
parents:
67
diff
changeset
|
2 .\" Copyright (c) 2020-2023 David Demelier <markand@malikania.fr> |
| 14 | 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 | |
|
74
67b3d13a5035
pasterd: make own HTML code for good
David Demelier <markand@malikania.fr>
parents:
72
diff
changeset
|
26 .Op Fl qv |
| 14 | 27 .Op Fl d Ar database-path |
| 28 .Op Fl t Ar theme-directory | |
| 29 .\" DESCRIPTION | |
| 30 .Sh DESCRIPTION | |
| 31 The | |
| 32 .Nm | |
|
74
67b3d13a5035
pasterd: make own HTML code for good
David Demelier <markand@malikania.fr>
parents:
72
diff
changeset
|
33 utility is a simple FastCGI program to host code snippets over a web interface. |
|
67b3d13a5035
pasterd: make own HTML code for good
David Demelier <markand@malikania.fr>
parents:
72
diff
changeset
|
34 It will show most recent public pastes and let users to create new one from a |
|
67b3d13a5035
pasterd: make own HTML code for good
David Demelier <markand@malikania.fr>
parents:
72
diff
changeset
|
35 web form. |
| 14 | 36 .Pp |
| 37 It supports: | |
| 38 .Bl -bullet -compat | |
| 39 .It | |
| 40 Listing of recent pastes, | |
|
33
511e2e865e15
doc: advertise myself in manual pages
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
41 .It |
| 14 | 42 Submission of new pastes, |
| 43 .It | |
|
32
a47801a1522a
doc: advertise searching function in pasterd.8
David Demelier <markand@malikania.fr>
parents:
21
diff
changeset
|
44 Searching existing pastes, |
|
a47801a1522a
doc: advertise searching function in pasterd.8
David Demelier <markand@malikania.fr>
parents:
21
diff
changeset
|
45 .It |
| 14 | 46 Language highlighting (depending on the theme), |
| 47 .It | |
| 48 Private pastes (not listed). | |
| 49 .El | |
| 50 .Pp | |
| 51 To store pastes, | |
| 52 .Nm | |
| 53 uses a SQLite database that must be writable by the CGI/FastCGI owner. See usage | |
| 54 below. | |
| 55 .Pp | |
| 56 Available options: | |
| 57 .Bl -tag -width Ds | |
| 58 .It Fl d Ar database-path | |
| 59 Specify an alternate path for the database. | |
| 60 .It Fl t Ar theme-directory | |
| 61 Specify an alternate directory for the theme. | |
|
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
62 .It Fl q |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
63 Do not log through syslog at all. |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
64 .It Fl v |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
65 Increase verbosity level. |
| 14 | 66 .El |
| 67 .\" USAGE | |
| 68 .Sh USAGE | |
| 69 The | |
| 70 .Nm | |
| 71 utility does not use configuration file as it does not need many adjustments, | |
| 72 instead every parameter could be passed by environment variables or options. | |
| 73 .Pp | |
| 74 By default, | |
| 75 .Nm | |
| 76 will try to use | |
| 77 .Pa @VARDIR@/paster/paster.db | |
| 78 database. | |
|
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
79 .\" LOGS |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
80 .Sh LOGS |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
81 The |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
82 .Nm |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
83 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
|
84 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
|
85 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
|
86 use syslog only. |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
87 .Pp |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
88 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
|
89 .Bd -literal -offset Ds |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
90 none < warnings (default) < info < debug |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
91 .Ed |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
92 .Pp |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
93 Use |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
94 .Fl q |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
95 or |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
96 .Va PASTERD_VERBOSITY=0 |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
97 if you want to disable syslog completely. |
| 14 | 98 .\" USING WITH FASTCGI |
| 99 .Sh USING WITH FASTCGI | |
| 100 The recommended way to use | |
| 101 .Nm | |
| 102 is to deploy using FastCGI. You can use the | |
| 103 .Xr kfcgi 8 | |
| 104 helper to spawn the process for you. | |
| 105 .Pp | |
| 106 Example: | |
| 107 .Bd -literal -offset Ds | |
| 108 kfcgi -p /var/www/paster -- pasterd -f -d paster.db -t siimple | |
| 109 .Ed | |
| 110 .Pp | |
| 111 Note: kfcgi chroot to the directory given, you must either statically link | |
| 112 pasterd at build time or deploy all required libraries. Also, themes directory | |
| 113 will need to be available in the chroot directory. In the above example, this | |
| 114 will effectively create a database | |
| 115 .Pa /var/www/paster/paster.db | |
| 116 and use the theme | |
| 117 .Pa /var/www/paster/siimple . | |
| 118 .Pp | |
| 119 Then, simply copy the desired theme into the directory. | |
| 120 .Bd -literal -offset Ds | |
| 121 cp -R @SHAREDIR@/paster/themes/siimple /var/www/paster | |
| 122 .Ed | |
| 123 .Pp | |
| 124 As an | |
| 125 .Em insecure | |
| 126 alternative, you can chroot to | |
| 127 .Pa / | |
| 128 to avoid static-linking and copying themes, using: | |
| 129 .Bd -literal -offset Ds | |
| 130 kfcgi -p / -- pasterd -f \e | |
| 131 -d /var/www/paster/paster.db \e | |
| 132 -t @SHAREDIR@/paster/themes/siimple | |
| 133 .Ed | |
| 134 .Pp | |
| 135 Both kfcgi invocations will create | |
| 136 .Pa /var/www/run/http.sock | |
| 137 with current user and group. Configure the web server to talk to that socket | |
| 138 and make sure it has appropriate file permissions otherwise see | |
| 139 .Fl u | |
| 140 option in | |
| 141 .Nm kfcgi . | |
| 142 See also the | |
| 143 .Xr kfcgi 8 | |
| 144 manual for more information. | |
| 145 .Pp | |
| 146 Next, configure the web server. | |
| 147 .Pp | |
| 148 Warning: at this moment, | |
| 149 .Nm | |
| 150 requires its own virtual host and can | |
| 151 .Em not | |
| 152 use a url. | |
| 153 .\" Server: nginx | |
| 154 .Ss Server: nginx | |
| 155 The nginx web server requires several parameters to run | |
| 156 .Nm . | |
| 157 .Bd -literal | |
| 158 server { | |
| 159 server_name mypaste.fr; | |
| 160 listen 80; | |
| 161 | |
| 162 location / { | |
| 163 fastcgi_param QUERY_STRING query_string; | |
| 164 fastcgi_param REQUEST_METHOD $request_method; | |
| 165 fastcgi_param CONTENT_TYPE $content_type; | |
| 166 fastcgi_param CONTENT_LENGTH $content_length; | |
| 167 fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; | |
| 168 fastcgi_param SCRIPT_NAME $fastcgi_script_name; | |
| 169 fastcgi_param PATH_INFO $document_uri; | |
| 170 fastcgi_param PATH_TRANSLATED $document_root$fastcgi_path_info; | |
| 171 fastcgi_param REQUEST_URI $request_uri; | |
| 172 fastcgi_param DOCUMENT_URI $document_uri; | |
| 173 fastcgi_param DOCUMENT_ROOT $document_root; | |
| 174 fastcgi_param SERVER_PROTOCOL $server_protocol; | |
| 175 fastcgi_param GATEWAY_INTERFACE CGI/1.1; | |
| 176 fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; | |
| 177 fastcgi_param REMOTE_ADDR $remote_addr; | |
| 178 fastcgi_param REMOTE_PORT $remote_port; | |
| 179 fastcgi_param SERVER_ADDR $server_addr; | |
| 180 fastcgi_param SERVER_PORT $server_port; | |
| 181 fastcgi_param SERVER_NAME $server_name; | |
| 182 fastcgi_param HTTPS $https; | |
| 183 fastcgi_pass unix:/var/www/run/httpd.sock; | |
| 184 } | |
| 185 } | |
| 186 .Ed | |
| 187 .\" ENVIRONMENT | |
| 188 .Sh ENVIRONMENT | |
| 189 The following environment variables are detected: | |
| 190 .Bl -tag -width Ds | |
| 191 .It Va PASTERD_DATABASE_PATH No (string) | |
| 192 Path to the SQLite database. | |
| 193 .It Va PASTERD_THEME_DIR No (string) | |
| 194 Directory containing the theme. | |
|
21
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
195 .It Va PASTERD_VERBOSITY No (number) |
|
21c103c33ac9
pasterd: improve verbosity, closes #2472
David Demelier <markand@malikania.fr>
parents:
14
diff
changeset
|
196 Verbosity level, 0 to disable completely. |
| 14 | 197 .El |
|
33
511e2e865e15
doc: advertise myself in manual pages
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
198 .\" AUTHORS |
|
511e2e865e15
doc: advertise myself in manual pages
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
199 .Sh AUTHORS |
|
511e2e865e15
doc: advertise myself in manual pages
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
200 .Nm |
|
511e2e865e15
doc: advertise myself in manual pages
David Demelier <markand@malikania.fr>
parents:
32
diff
changeset
|
201 was written by David Demelier <markand@malikania.fr> |
| 14 | 202 .\" SEE ALSO |
| 203 .Sh SEE ALSO | |
| 204 .Xr paster 8 , | |
| 205 .Xr kfcgi 8 |