"Fossies" - the Fresh Open Source Software Archive

Member "shellinabox-2.20/shellinabox/shellinaboxd.man.in" (9 Nov 2016, 27655 Bytes) of package /linux/privat/shellinabox-2.20.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "shellinaboxd.man.in": 2.19_vs_2.20.

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