]>
Commit | Line | Data |
---|---|---|
7460295f MG |
1 | '\" t |
2 | .\" shellinaboxd.man -- Make command line applications available as AJAX web applications | |
e0bb8a33 | 3 | .\" Copyright (C) 2008-2009 Markus Gutschke <markus@shellinabox.com> |
7460295f MG |
4 | .\" |
5 | .\" This program is free software; you can redistribute it and/or modify | |
6 | .\" it under the terms of the GNU General Public License version 2 as | |
7 | .\" published by the Free Software Foundation. | |
8 | .\" | |
9 | .\" This program is distributed in the hope that it will be useful, | |
10 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
11 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
12 | .\" GNU General Public License for more details. | |
13 | .\" | |
14 | .\" You should have received a copy of the GNU General Public License along | |
15 | .\" with this program; if not, write to the Free Software Foundation, Inc., | |
16 | .\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. | |
17 | .\" | |
18 | .\" In addition to these license terms, the author grants the following | |
19 | .\" additional rights: | |
20 | .\" | |
21 | .\" If you modify this program, or any covered work, by linking or | |
22 | .\" combining it with the OpenSSL project's OpenSSL library (or a | |
23 | .\" modified version of that library), containing parts covered by the | |
24 | .\" terms of the OpenSSL or SSLeay licenses, the author | |
25 | .\" grants you additional permission to convey the resulting work. | |
26 | .\" Corresponding Source for a non-source form of such a combination | |
27 | .\" shall include the source code for the parts of OpenSSL used as well | |
28 | .\" as that of the covered work. | |
29 | .\" | |
30 | .\" You may at your option choose to remove this additional permission from | |
31 | .\" the work, or from any part of it. | |
32 | .\" | |
33 | .\" It is possible to build this program in a way that it loads OpenSSL | |
34 | .\" libraries at run-time. If doing so, the following notices are required | |
35 | .\" by the OpenSSL and SSLeay licenses: | |
36 | .\" | |
37 | .\" This product includes software developed by the OpenSSL Project | |
38 | .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/) | |
39 | .\" | |
40 | .\" This product includes cryptographic software written by Eric Young | |
41 | .\" (eay@cryptsoft.com) | |
42 | .\" | |
43 | .\" | |
44 | .\" The most up-to-date version of this program is always available from | |
45 | .\" http://shellinabox.com | |
46 | .\" | |
47 | .TH SHELLINABOXD 1 "Dec 25, 2008" | |
48 | .SH NAME | |
49 | shellinaboxd \- publish command line shell through AJAX interface | |
50 | .SH SYNOPSIS | |
51 | .TP | |
52 | .B shellinaboxd | |
53 | [\ \fB-b\fP\ | \fB--background\fP[\fB=\fP\fIpidfile\fP]\ ] | |
2809cd15 | 54 | #ifdef HAVE_OPENSSL |
7460295f | 55 | [\ \fB-c\fP\ | \fB--cert=\fP\fIcertdir\fP\ ] |
2809cd15 | 56 | #endif |
293c6c6b | 57 | [\ \fB--cert-fd=\fP\fIfd\fP\ ] |
1f771613 | 58 | [\ \fB--css=\fP\fIfilename\fP\ ] |
d1edcc0e | 59 | [\ \fB--cgi\fP[\fB=\fP\fIportrange\fP]\ ] |
7460295f MG |
60 | [\ \fB-d\fP\ | \fB--debug\fP\ ] |
61 | [\ \fB-f\fP\ | \fB--static-file=\fP\fIurl\fP:\fIfile\fP\ ] | |
62 | [\ \fB-g\fP\ | \fB--group=\fP\fIgid\fP\ ] | |
63 | [\ \fB-h\fP\ | \fB--help\fP\ ] | |
f0c6fd39 | 64 | [\ \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP]\ ] |
5ba94b37 | 65 | [\ \fB--localhost-only\fP\ ] |
46f2036a | 66 | [\ \fB--no-beep\fP\ ] |
7460295f MG |
67 | [\ \fB-n\fP\ | \fB--numeric\fP\ ] |
68 | [\ \fB-p\fP\ | \fB--port=\fP\fIport\fP\ ] | |
69 | [\ \fB-s\fP\ | \fB--service=\fP\fIservice\fP\ ] | |
2809cd15 | 70 | #ifdef HAVE_OPENSSL |
7460295f | 71 | [\ \fB-t\fP\ | \fB--disable-ssl\fP\ ] |
2809cd15 | 72 | #endif |
b624088c | 73 | [\ \fB--disable-ssl-menu\fP\ ] |
7460295f | 74 | [\ \fB-q\fP\ | \fB--quiet\fP\ ] |
d9b6bc27 | 75 | [\ \fB-u\fP\ | \fB--user=\fP\fIuid\fP\ ] |
7460295f MG |
76 | [\ \fB-v\fP\ | \fB--verbose\fP\ ] |
77 | [\ \fB--version\fP\ ] | |
78 | .SH DESCRIPTION | |
79 | The | |
80 | .B shellinaboxd | |
81 | daemon implements a webserver that listens on the specified | |
82 | .IR port . | |
83 | The web server publishes one or more | |
84 | .I services | |
85 | that will be displayed in a VT100 emulator implemented as an AJAX web | |
86 | application. By default, the port is 4200 and the default service URL is | |
87 | .IR http://localhost:4200/ . | |
88 | .P | |
89 | If no particular | |
90 | .I service | |
91 | was requested, the server launches | |
92 | .B /bin/login | |
93 | querying the user for their username and password. It then starts the | |
94 | user's default login shell. | |
95 | .P | |
96 | Any modern JavaScript and CSS enabled browser will be able to access the | |
97 | published | |
98 | .I service | |
99 | without requiring additional plugins. | |
100 | .SH OPTIONS | |
101 | The following command line parameters control the operation of the daemon: | |
102 | .TP \w'\-b\ |\ 'u | |
103 | \fB-b\fP\ | \fB--background\fP[\fB=\fP\fIpidfile\fP] | |
104 | Launch | |
105 | .B shellinaboxd | |
106 | as a background daemon process. Optionally, write the process id to | |
107 | .IR pidfile . | |
2809cd15 | 108 | #ifdef HAVE_OPENSSL |
7460295f | 109 | .TP |
d9b6bc27 | 110 | \fB-c\fP\ |\ \fB--cert=\fP\fIcertdir\fP |
7460295f MG |
111 | If built with SSL/TLS support enabled, the daemon will look in |
112 | .I certdir | |
113 | for any certificates. If unspecified, this defaults to the current | |
114 | working directory. | |
115 | ||
116 | If the browser negotiated a | |
117 | .B Server Name Identification | |
118 | the daemon will look for a matching | |
119 | .I certificate-\f[BI]SERVERNAME\fP.pem | |
120 | file. This allows for virtual hosting of multiple server names on the | |
121 | same IP address and port. | |
122 | ||
123 | If no | |
124 | .B SNI | |
125 | handshake took place, it falls back on using the certificate in the | |
126 | .I certificate.pem | |
127 | file. | |
128 | ||
129 | The administrator should make sure that there are matching | |
130 | certificates for each of the virtual hosts on this server, and that | |
131 | there is a generic | |
132 | .I certificate.pem | |
133 | file. | |
134 | ||
135 | If no suitable certificate is installed, | |
136 | .B shellinaboxd | |
137 | will attempt to invoke | |
138 | .B /usr/bin/openssl | |
139 | and create a new self-signed certificate. This only succeeds if, after | |
140 | dropping privileges, | |
141 | .B shell\%ina\%boxd | |
142 | has write permissions for | |
143 | .IR certdir . | |
144 | ||
145 | Most browsers show a warning message when encountering a self-signed | |
146 | certificate and then allow the user the option of accepting the | |
147 | certificate. Due to this usability problem, and due to the perceived | |
148 | security implications, the use of auto-generated self-signed | |
149 | certificates is intended for testing or in intranet deployments, only. | |
150 | .TP | |
dc6575f2 MG |
151 | \fB--cert-fd=\fP\fIfd\fP |
152 | Instead of providing a | |
153 | .B --cert | |
154 | directory, it is also possible to provide a filedescriptor | |
155 | .I fd | |
156 | where the certificate and key can be retrieved. While this option disables | |
157 | .B SNI | |
158 | support, it does offer an alternative solution for securely providing | |
159 | the private key data to the daemon. | |
2809cd15 | 160 | #endif |
dc6575f2 | 161 | .TP |
1f771613 MG |
162 | \fB--css=\fP\fIfilename\fP |
163 | Sometimes, it is not necessary to replace the entire style sheet using the | |
164 | .B --static-file | |
165 | option. But instead a small incremental change should be made to the visual | |
166 | appearance of the terminal. The | |
167 | .B --css | |
168 | option provides a means to append additional style rules to the end of | |
169 | the default | |
170 | .B styles.css | |
171 | sheet. More than one | |
172 | .B --css | |
173 | option can be given on the same command line. | |
174 | .TP | |
d1edcc0e MG |
175 | \fB--cgi\fP[\fB=\fP\fIportrange\fP] |
176 | Instead of running | |
177 | .B shellinaboxd | |
178 | as a permanent process, it can be demand-loaded as a CGI web server | |
179 | extension. When doing so, it will spawn a server that lives for the | |
180 | duration of the user's session. If an optional | |
181 | .I portrange | |
182 | of the form | |
183 | .BR MINPORT-MAXPORT | |
184 | has been provided, the server limits itself to these port numbers. They | |
185 | should be configured to pass through the firewall. | |
186 | ||
187 | The | |
188 | .B --cgi | |
189 | option is mutually exclusive with the | |
190 | .B --background | |
191 | and | |
192 | .B --port | |
193 | options. | |
194 | ||
195 | In order to be useful as a CGI script, the | |
196 | .B shellinaboxd | |
197 | binary probably will have to be made | |
198 | .BR setuid-root . | |
199 | This is currently a discouraged configuration. Use with care. | |
200 | .TP | |
7460295f | 201 | \fB-d\fP\ |\ \fB--debug\fP |
d9b6bc27 | 202 | Enables debugging mode, resulting in lots of log messages on |
7460295f MG |
203 | .IR stderr . |
204 | This option is mutually exclusive with | |
205 | .B --quiet | |
206 | and | |
207 | .BR --verbose . | |
208 | .TP | |
209 | \fB-f\fP\ |\ \fB--static-file=\fP\fIurl\fP:\fIfile\fP | |
210 | The daemon serves various built-in resources from URLs underneath the | |
211 | .I service | |
212 | mount points. One or more | |
213 | .B --static-file | |
214 | options allow for overriding these resources with customized externally | |
215 | provided | |
216 | .IR files . | |
217 | The | |
218 | .I url | |
219 | can either be an absolute or a relative path. In the former case, it overrides | |
220 | exactly one built-in resource for one specific | |
221 | .IR service , | |
222 | whereas in the latter case it overrides resources for each defined | |
223 | .IR service . | |
224 | ||
225 | The following resources are available for customization: | |
226 | .RS | |
227 | .TP \w'ShellInABox.js\ \ \ 'u | |
228 | .B beep.wav | |
229 | audio sample that gets played whenever the terminal BEL is sounded. | |
230 | .TP | |
231 | .B favicon.ico | |
232 | favicon image file that is displayed in the browser's navigation bar. | |
233 | .TP | |
234 | .B ShellInABox.js | |
235 | JavaScript file implementing the AJAX terminal emulator. | |
236 | .TP | |
237 | .B styles.css | |
238 | CSS style file that controls the visual appearance of the terminal. | |
239 | .P | |
240 | It is not recommended to override the root HTML page for a particular | |
241 | .IR service . | |
242 | Instead, move the service to an anonymous URL and serve a | |
243 | .I static-file | |
244 | that references the | |
245 | .I service | |
246 | in an | |
247 | .IR <iframe> . | |
248 | ||
249 | Instead of a | |
250 | .IR file , | |
251 | it is possible to provide the name of a directory. This turns | |
252 | .B shellinaboxd | |
253 | into a simple web server that publishes all of the files in that | |
254 | particular directory. This option can be helpful when publishing a more | |
255 | complex root HTML page. | |
256 | .RE | |
257 | .TP | |
258 | \fB-g\fP\ |\ \fB--group=\fP\fIgid\fP | |
259 | When started as | |
260 | .BR root , | |
261 | the server drops most privileges at start up. Unless overridden by the | |
262 | .B --group | |
263 | option, it switches to | |
264 | .BR nogroup . | |
265 | ||
d1edcc0e MG |
266 | When already running as an unprivileged user, group changes are not |
267 | possible. | |
7460295f MG |
268 | |
269 | If running with SSL/TLS support enabled, the certificates must be | |
270 | accessible to the unprivileged user and/or group that the daemon | |
271 | runs as. | |
272 | .TP | |
273 | \fB-h\fP\ |\ \fB--help\fP | |
274 | Display a brief usage message showing the valid command line parameters. | |
275 | .TP | |
f0c6fd39 MG |
276 | \fB--linkify\fP=[\fBnone\fP|\fBnormal\fP|\fBaggressive\fP] |
277 | the daemon attempts to recognize URLs in the terminal output and makes them | |
278 | clickable. This is not neccessarily a fool-proof process and both false | |
279 | negatives and false positives are possible. By default, only URLs starting | |
280 | with a well known protocol of | |
281 | .BR http:// ,\ https:// ,\ ftp:// ,\ or\ mailto: | |
282 | are recognized. In | |
283 | .B aggressive | |
284 | mode, anything that looks like a hostname, URL or e-mail address is | |
285 | recognized, even if not preceded by a protocol. | |
286 | .TP | |
5ba94b37 MG |
287 | \fB--localhost-only\fP |
288 | Normally, | |
289 | .B shellinaboxd | |
290 | listens on all available network interfaces. When operating behind a | |
291 | reverse-proxy that is not always desirable. This command line option | |
292 | tells the daemon to only listen on the loopback interface. | |
293 | .TP | |
46f2036a MG |
294 | \fB--no-beep\fP |
295 | not only are audible signals undesired in some working environments, but | |
296 | browser support for media playback is often buggy, too. Setting this option | |
297 | suppresses all audio playback and enables the visual bell by default. | |
298 | .TP | |
7460295f MG |
299 | \fB-n\fP\ |\ \fB--numeric\fP |
300 | When running in | |
301 | .B --verbose | |
302 | mode, the daemon prints an | |
303 | .IR Apache -style | |
304 | log file to | |
305 | .IR stderr . | |
306 | By default, host names of peers get resolved | |
307 | before logging them. As DNS look-ups can be expensive, it is possible | |
308 | to request logging of numeric IP addresses, instead. | |
309 | .TP | |
310 | \fB-p\fP\ |\ \fB--port=\fP\fIport\fP | |
311 | Unless overridden by this option, the web server listens on port 4200 | |
312 | for incoming HTTP and HTTPS requests. | |
313 | ||
314 | .B shellinaboxd | |
315 | can distinguish between SSL/TLS requests and unencrypted requests. It | |
316 | also knows how to negotiate | |
317 | .B Server Name | |
318 | .BR Identification , | |
319 | allowing the use of a single port for all types of requests even when | |
320 | virtual hosting. | |
321 | .TP | |
322 | \fB-s\fP\ |\ \fB--service=\fP\fIservice\fP | |
323 | One or more services can be registered on different URL paths: | |
324 | .in +4 | |
2809cd15 | 325 | \fISERVICE\fP := <url-path> ':' \fIAPPLICATION\fP |
7460295f | 326 | .in |
2809cd15 MG |
327 | |
328 | There is a pre-defined \fIapplication\fP, 'LOGIN', which causes the | |
7460295f MG |
329 | daemon to invoke |
330 | .B /bin/login | |
2809cd15 MG |
331 | requesting the user's name and password, and starting his |
332 | login shell. This is the default option for the | |
333 | .B root | |
334 | user, if no | |
7460295f MG |
335 | .B --service |
336 | was defined. Starting | |
337 | .B /bin/login | |
338 | requires | |
339 | .B root | |
340 | privileges. | |
341 | ||
2809cd15 MG |
342 | There is another pre-defined \fIapplication\fP, 'SSH'. Instead of invoking |
343 | .BR /bin/login , | |
344 | it calls | |
345 | .BR ssh . | |
346 | This is the default option for unprivileged users, if no | |
347 | .B --service | |
348 | was defined. This operation is available to both privileged and regular | |
349 | users. If the optional \fIhost\fP parameter is omitted, | |
350 | .B shellinaboxd | |
351 | connects to | |
352 | .BR localhost . | |
353 | ||
7460295f MG |
354 | Alternatively, an \fIapplication\fP can be specified by providing a |
355 | \fIuser\fP description, a working directory, and a command line: | |
356 | .in +4 | |
2809cd15 | 357 | \fIAPPLICATION\fP := 'LOGIN' | 'SSH' [ ':' <host> ] | \fIUSER\fP ':' \fICWD\fP ':' <cmdline> |
7460295f | 358 | |
bf1ec4d2 MG |
359 | #ifdef HAVE_PAM |
360 | .in | |
7460295f MG |
361 | The keyword 'AUTH' indicates that the \fIuser\fP information should |
362 | be requested interactively, instead of being provided as part of the | |
363 | \fIservice\fP description: | |
364 | .in +4 | |
bf1ec4d2 | 365 | #endif |
bf1ec4d2 | 366 | #ifdef HAVE_PAM |
2809cd15 MG |
367 | \fIUSER\fP := 'AUTH' | |
368 | #endif | |
369 | #ifndef HAVE_PAM | |
370 | \fIUSER\fP := | |
bf1ec4d2 MG |
371 | #endif |
372 | <username> ':' <groupname> | |
7460295f MG |
373 | .in |
374 | ||
375 | The working directory can either be given as an absolute path, or it | |
376 | can be the user's home directory: | |
377 | .in +4 | |
378 | \fICWD\fP := 'HOME' : <dir> | |
379 | .in | |
380 | ||
381 | The <cmdline> supports expansion of variables of the form ${VAR}. | |
382 | Supported variables are: | |
383 | .RS | |
384 | .TP \w'${columns}\ \ 'u | |
385 | .B ${columns} | |
386 | number of columns. | |
387 | .TP | |
388 | .B ${gid} | |
389 | numeric group id. | |
390 | .TP | |
391 | .B ${group} | |
392 | group name. | |
393 | .TP | |
394 | .B ${home} | |
395 | home directory. | |
396 | .TP | |
397 | .B ${lines} | |
398 | number of rows. | |
399 | .TP | |
400 | .B ${peer} | |
401 | name of remote peer. | |
402 | .TP | |
403 | .B ${uid} | |
404 | numeric user id. | |
405 | .TP | |
406 | .B ${user} | |
407 | user name. | |
408 | .P | |
409 | Other than the default environment variables of | |
410 | .BR $TERM , | |
411 | .B $COLUMNS | |
412 | and | |
413 | .BR $LINES , | |
414 | services can have environment variables passed to them, by preceding | |
415 | the <cmdline> with space separated variable assignments of the form | |
416 | .IR KEY = VALUE . | |
417 | ||
418 | The <cmdline> supports single and double quotes, as well as | |
419 | backslashes for escaping characters in the familiar fashion. | |
420 | ||
421 | Please note that when invoking | |
422 | .B shellinaboxd | |
423 | from a command line shell, additional quoting might be required to | |
424 | prevent the shell from expanding the variables prior to passing them | |
425 | to the daemon. | |
426 | ||
427 | If no explicit | |
428 | .B --service | |
429 | has been requested, | |
430 | .B shellinaboxd | |
2809cd15 MG |
431 | defaults to attaching the default service to the root directory of the web |
432 | server. For | |
433 | .BR root , | |
434 | this is | |
435 | .BR /bin/login , | |
436 | and for unprivileged users, this is \fBssh localhost\fP. This is equivalent | |
437 | to saying | |
438 | .BR --service=/:LOGIN , | |
439 | or | |
440 | .BR --service=/:SSH , | |
441 | respectively. | |
7460295f | 442 | .RE |
2809cd15 | 443 | #ifdef HAVE_OPENSSL |
7460295f MG |
444 | .TP |
445 | \fB-t\fP\ |\ \fB--disable-ssl\fP | |
446 | By default, | |
447 | .B shellinaboxd | |
448 | redirectes all incoming HTTP requests to their equivalent HTTPS | |
449 | URLs. If promoting of connections to encrypted SSL/TLS sessions is | |
450 | undesired, this behavior can be disabled. | |
451 | ||
452 | This option is also useful during testing or for deployment in trusted | |
453 | intranets, if SSL certificates are unavailable. | |
2809cd15 | 454 | #endif |
7460295f | 455 | .TP |
b624088c MG |
456 | \fB--disable-ssl-menu\fP |
457 | If the user should not be able to switch between HTTP and HTTPS modes, this | |
458 | choice can be removed from the context menu. The user can still make this | |
459 | choice by directly going to the appropriate URL. | |
460 | .TP | |
7460295f MG |
461 | \fB-q\fP\ |\ \fB--quiet\fP |
462 | Surpresses all messages to | |
d9b6bc27 | 463 | .IR stderr . |
7460295f MG |
464 | This option is mutually exclusive with |
465 | .B --debug | |
466 | and | |
467 | .BR --verbose . | |
468 | .TP | |
469 | \fB-u\fP\ |\ \fB--user=\fP\fIuid\fP | |
470 | If started as | |
471 | .BR root , | |
472 | the server drops privileges by changing to | |
473 | .BR nobody , | |
474 | unless the | |
475 | .I uid | |
476 | has been overridden by this option. | |
477 | ||
478 | For more details, refer to the description of the | |
479 | .B --group | |
480 | option. | |
481 | .TP | |
482 | \fB-v\fP\ |\ \fB--verbose\fP | |
483 | Enables logging of | |
484 | .IR Apache -style | |
485 | log file to | |
486 | .IR stderr . | |
487 | This option is mutually exclusive with | |
488 | .B --debug | |
489 | and | |
490 | .BR --quiet . | |
491 | .TP | |
492 | \fB--version\fP | |
493 | Prints the version number of the binary and exits. | |
494 | .SH CONFIGURATION | |
495 | There are no configuration files or permanent settings for | |
496 | .BR shell\%ina\%boxd . | |
497 | A small number of run-time configuration options are available from a | |
498 | context menu that becomes available when clicking the right mouse button. | |
499 | .SH EXAMPLES | |
500 | .TP \w'shellinaboxd\ 'u | |
3fa8757a MG |
501 | .B shellinaboxd |
502 | Attaches a web-enabled login shell to | |
503 | .IR https://localhost:4200/ . | |
504 | If the user connected without SSL, the session will automatically be promoted. | |
505 | Unless SSL certificates can be found in the current directory, the daemon will | |
506 | automatically generate suitable self-signed certificates. If the command was | |
507 | invoked by a non-\fBroot\fP user, the daemon uses | |
508 | .B ssh | |
509 | instead of | |
510 | .B /bin/login | |
511 | for the session. | |
512 | .TP | |
7460295f MG |
513 | .B shellinaboxd -t |
514 | Attaches a web-enabled login shell to | |
515 | .I http://localhost:4200/ | |
3fa8757a | 516 | with SSL/TLS support disabled. |
7460295f MG |
517 | .TP |
518 | .B shellinaboxd -t -f beep.wav:/dev/null | |
519 | Runs all services with the audible-bell permanently disabled. | |
520 | .TP | |
521 | .B shellinaboxd -t -s /:AUTH:HOME:/bin/bash | |
522 | Interactively request the user's name and password prior to launching | |
523 | a Bourne shell. This command can be run by unprivileged users. But if | |
524 | doing so, it only allows this particular user to log in. | |
525 | .TP | |
65f7545e | 526 | .B shellinaboxd -c certificates -u shellinabox -g shellinabox |
7460295f MG |
527 | If the |
528 | .B certificates | |
529 | directory exists and is writable by the | |
65f7545e MG |
530 | .B shellinabox |
531 | user and group, self-signed SSL certificates will be generated in this | |
532 | directory. This might require creating an appropriately named user first. | |
533 | Running this command as | |
7460295f MG |
534 | .B root |
535 | allows any user on the system to log in at | |
536 | .BR http://localhost:4200/ . | |
537 | Sessions will automatically be promoted to SSL/TLS. | |
538 | .TP | |
539 | .B shellinaboxd -t -s /:LOGIN -s /who:nobody:nogroup:/:w | |
540 | In addition to the login shell at | |
541 | .IR http://localhost:4200 , | |
542 | show a list of currently logged in users when accessing | |
543 | .IR http://localhost:4200/who . | |
544 | This command must be run as | |
545 | .B root | |
546 | in order to be able to change to | |
547 | .B nobody:nogroup | |
548 | as requested by the service description. | |
549 | .TP | |
550 | .B shellinaboxd -t -s '/:root:root:/:wy60 -c /bin/login' | |
551 | Instead of the standard | |
552 | .B ANSI/VT100 | |
553 | terminal, publish a | |
554 | .B Wyse 60\*(Tm | |
555 | terminal. Again, this command should be run as | |
556 | .BR root . | |
1f771613 MG |
557 | .TP |
558 | #ifndef DPKGBUILD | |
559 | .B shellinaboxd --css white-on-black.css | |
560 | #endif | |
561 | #ifdef DPKGBUILD | |
562 | .B shellinaboxd --css /usr/share/doc/shellinabox/white-on-black.css | |
563 | #endif | |
564 | Loads the | |
565 | .B white-on-black.css | |
566 | style sheet | |
567 | #ifndef DPKGBUILD | |
568 | from the current directory | |
569 | #endif | |
570 | and appends it to the built-in | |
571 | .B styles.css | |
572 | sheet. This causes the terminal to render white text on a black background. | |
7460295f MG |
573 | .P |
574 | .SH DIAGNOSTICS | |
575 | The daemon returns a non-zero exit code in case of failure. With the | |
576 | exception of a small number of common error cases that are handled | |
577 | explicitly, most errors result in printing a | |
578 | .I \(dqCheck failed\(dq | |
579 | message. This does not typically indicate a bug in the program but is | |
580 | instead its normal way of reporting errors. | |
581 | ||
582 | Common failure conditions are reusing a port that is already in use, | |
583 | lack of sufficient privileges to run a service, failure to find | |
584 | SSL/TLS certificates, and failure to write newly generated | |
585 | certificates to the certification directory. | |
1f771613 MG |
586 | #ifdef DPKGBUILD |
587 | .SH FILES | |
588 | .TP 10 | |
589 | .I /etc/default/shellinabox | |
590 | The system-wide installation of | |
591 | .B shellinaboxd | |
592 | can be configured by editing this file. After making any changes, restart | |
593 | the daemon with \fBsudo service shellinabox restart\fP. | |
594 | .TP | |
595 | .I /etc/init.d/shellinabox | |
596 | This is the system-wide service definition. Usually, there is no need to | |
597 | edit this file. | |
598 | .TP | |
599 | .I /var/lib/shellinabox | |
600 | This directory contains the certificate files that | |
601 | .B shellinaboxd | |
602 | uses when serving encrypted SSL sessions. If suitable files do not exist, yet, | |
603 | it tries to populate the directory with self-signed certificates the first | |
604 | time a particular certificate is needed. Over time, it should contain | |
605 | \fBcertificate.pem\fP, \fBcertificate-localhost.pem\fP, and | |
606 | \fBcertificate-\fP\fIHOSTNAME\fP\fB.pem\fP. | |
607 | .TP | |
608 | .I /var/run/shellinaboxd.pid | |
609 | This file is created any time the system-wide service gets started. | |
610 | #endif | |
7460295f MG |
611 | .SH "SEE ALSO" |
612 | .BR chmod (1), | |
613 | .BR last (1), | |
614 | .BR login (1), | |
615 | .BR sh (1), | |
616 | .BR shells (5), | |
617 | .BR openssl (1SSL), | |
618 | .BR w (1), | |
619 | .BR wy60 (1), | |
620 | .BR xterm (1). | |
621 | .SH SECURITY | |
622 | The daemon uses privilege separation techniques to allow it to drop | |
623 | privileges early. It is aware of setuid flags and restricts some | |
624 | operations when launched as a setuid application. | |
625 | ||
626 | Despite these safety features, a bug could conceivably lead to a | |
627 | determined attacker gaining elevated privileges. It is therefore | |
628 | strongly discouraged to set the setuid flag on the binary. | |
629 | ||
630 | The expected deployment would be from a system | |
631 | .I rc | |
632 | script launched by | |
633 | .BR /sbin/init . | |
634 | For extra security, the | |
635 | .B --group | |
636 | and | |
637 | .B --user | |
638 | options should be used to change to a dedicated user. | |
639 | .SH AUTHOR | |
e0bb8a33 | 640 | Copyright (C) 2008-2009 by Markus Gutschke |
7460295f MG |
641 | .RI < "markus@shellinabox.com" >. |
642 | .P | |
643 | This program is free software; you can redistribute it and/or modify | |
644 | it under the terms of the GNU General Public License version 2 as | |
645 | published by the Free Software Foundation. | |
646 | .P | |
647 | This program is distributed in the hope that it will be useful, | |
648 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
649 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
650 | GNU General Public License for more details. | |
651 | .P | |
652 | You should have received a copy of the GNU General Public License | |
653 | along with this program; if not, write to the Free Software | |
654 | Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 | |
655 | USA | |
656 | .P | |
657 | In addition to these license terms, the author grants the following | |
658 | additional rights: | |
659 | .P | |
660 | If you modify this program, or any covered work, by linking or | |
661 | combining it with the OpenSSL project's OpenSSL library (or a | |
662 | modified version of that library), containing parts covered by the | |
663 | terms of the OpenSSL or SSLeay licenses, the author | |
664 | grants you additional permission to convey the resulting work. | |
665 | Corresponding Source for a non-source form of such a combination | |
666 | shall include the source code for the parts of OpenSSL used as well | |
667 | as that of the covered work. | |
668 | .P | |
669 | You may at your option choose to remove this additional permission from | |
670 | the work, or from any part of it. | |
671 | .P | |
672 | If you would like to negotiate different licensing terms that are | |
673 | compatible for integration with other projects, please contact the | |
674 | author. | |
675 | #ifdef HAVE_OPENSSL | |
676 | .P | |
677 | If the OpenSSL | |
678 | system libraries can be found at run-time, they will be invoked by | |
679 | .B shellinaboxd | |
680 | to provide SSL/TLS support. The OpenSSL and SSLeay | |
681 | licenses require the following notices: | |
682 | .P | |
683 | This product includes software developed by the OpenSSL Project | |
684 | for use in the OpenSSL Toolkit. (http://www.openssl.org/) | |
685 | .P | |
686 | This product includes cryptographic software written by Eric Young | |
687 | (eay@cryptsoft.com) | |
688 | #endif | |
689 | .SH BUGS | |
690 | Due to browser limitations, some features might not be available to | |
691 | users of all browers. | |
692 | .P | |
693 | Konqueror does not allow for reliable interception of | |
694 | .I CTRL | |
695 | keys. If you press a key together with the | |
696 | .I CTRL | |
697 | modifier, it continues performing the browser's predefined behavior for | |
698 | this particular key combination. In most cases, it also fails to report | |
699 | the correct key to the terminal emulator. As a work-around, pressing | |
700 | both the | |
701 | .I CTRL | |
702 | and the | |
703 | .I WINDOWS | |
704 | key sometimes works. | |
705 | .P | |
706 | Some browsers, most notably IE on Windows, disallow interception of | |
707 | .I ALT | |
708 | keys and always interpret these keys as menu accelerators. As a | |
709 | work-around, many UNIX applications allow pressing | |
710 | .IR ESC , | |
711 | instead of | |
712 | .IR ALT . | |
713 | .P | |
714 | When using non-US keyboard layouts, some browser do not allow for | |
715 | reliably determining shifted | |
716 | .I ALT | |
717 | keys. Please report these cases if they turn out to be a problem, as | |
718 | work-arounds might be possible. | |
719 | .P | |
720 | Access to the native clipboard is typically not possible. Instead, an | |
721 | internal clipboard accessible from the right-button context menu is used | |
722 | for all but IE. | |
723 | .P | |
724 | Some browsers restrict the number of concurrent connections to a | |
725 | server. This restricts how many AJAX terminals can be opened | |
726 | simultaneously. If this becomes a problem, users can typically | |
727 | reconfigure their browsers to raise the limit. | |
46f2036a MG |
728 | .P |
729 | There have been reports of the VLC plugin on Linux/x86_64 crashing Firefox | |
730 | when the browser page gets reloaded. Setting the | |
731 | .B --no-beep | |
732 | option eliminates all references to VLC and thus appears to work around | |
733 | this crash. |