diff --git a/src/guacd/Makefile.am b/src/guacd/Makefile.am index 1833fbaf..2b9afe04 100644 --- a/src/guacd/Makefile.am +++ b/src/guacd/Makefile.am @@ -25,7 +25,10 @@ AUTOMAKE_OPTIONS = foreign AM_CFLAGS = -Werror -Wall -pedantic @LIBGUAC_INCLUDE@ @COMMON_INCLUDE@ sbin_PROGRAMS = guacd -man_MANS = man/guacd.8 + +man_MANS = \ + man/guacd.8 \ + man/guacd.conf.5 noinst_HEADERS = \ client.h \ diff --git a/src/guacd/man/guacd.8 b/src/guacd/man/guacd.8 index 74edec6f..225a9225 100644 --- a/src/guacd/man/guacd.8 +++ b/src/guacd/man/guacd.8 @@ -1,4 +1,4 @@ -.TH guacd 8 "21 Jul 2014" "version 0.9.2" "Guacamole" +.TH guacd 8 "9 Sep 2014" "version 0.9.2" "Guacamole" . .SH NAME guacd \- Guacamole proxy daemon @@ -78,5 +78,8 @@ this instance of will require SSL/TLS enabled in the client (the web application). If this option is not given, communication with guacd must be unencrypted. . +.SH SEE ALSO +.BR guacd.conf (5) +. .SH AUTHOR Written by Michael Jumper diff --git a/src/guacd/man/guacd.conf.5 b/src/guacd/man/guacd.conf.5 new file mode 100644 index 00000000..90b18c5a --- /dev/null +++ b/src/guacd/man/guacd.conf.5 @@ -0,0 +1,149 @@ +.TH guacd.conf 5 "9 Sep 2014" "version 0.9.2" "Guacamole" +. +.SH NAME +/etc/guacamole/guacd.conf \- Configuration file for guacd +. +.SH DESCRIPTION +.B /etc/guacamole/guacd.conf +is the configuration file for the Guacamole proxy daemon used by the Guacamole +web application and framework, +.B guacd. +Use of this file is entirely optional, and all of its options can be specified +from the command line when running +.B guacd. +If you provide both the +.B guacd.conf +file and command line options, the command line options will take precendence. +. +.SH SYNTAX +.B guacd.conf +is made up of sections, where each section contains a set of parameter/value +pairs. The parameter available are dictated by the section in use, and +parameters may only be specified within a section. +.P +The beginning of each section is denoted with a section name in brackets, and +each section ends implicitly with the beginning of a new section, or at the end +of the file. +.TP +\fB[server]\fR +Contains parameters which control how +.B guacd +behaves as a server, from a network perspective. +.TP +\fB[daemon]\fR +Parameters which configure how +.B guacd +behaves as a daemon, such as what file should contain the PID, if any. +.TP +\fB[ssl]\fR +Parameters which control the SSL support of +.B guacd +, such as the certificate and private key used for encryption of the Guacamole +protocol. This section and its parameters are only valid if +.B guacd +was built with SSL support. +.P +Parameters within sections are written as a parameter name, followed by an +equals sign, followed by the parameter value, all on one line. Comments may be +placed anywhere, and consist of arbitrary text following a +.B # +symbol until end-of-line: +.TP +\fIname\fR \fB=\fR \fIvalue\fR \fB#\fR \fISome arbitrary comment text\fR +.P +Beware that it is the combination of the section name with the parameter name +that makes up the fully qualified name of a parameter. Each parameter +absolutely +.I must +be placed only within its proper section, or +.B guacd.conf +will fail to be parsed, and +.B guacd +will not start. +.P +If special characters need to be placed within a parameter value, such as +whitespace, \fB#\fR, \fB"\fR, or \fB\\\fR, the entire value must be enclosed in +double quotes, and each occurrence of \fB"\fR or \fB\\\fR within the value must +be escaped with backslashes: +.TP +\fIname\fR \fB=\fR \fB"\fR\fIquoted # value \\\\ with \\" special characters\fR\fB"\fR +. +.SH SERVER PARAMETERS +.TP +\fBbind_host\fR \fB=\fR \fIHOSTNAME\fR +Requires +.B guacd +to bind to a specific host when listening for connections. By default, +.B guacd +will bind to localhost only. +.TP +\fBbind_port\fR \fB=\fR \fIPORT\fR +Requires +.B guacd +to bind to a specific port when listening for connections. By default, +.B guacd +will bind to port 4822. +. +.SH DAEMON PARAMETERS +.TP +\fBpid_file\fR \fB=\fR \fIFILE\fR +Causes +.B guacd +to write its PID to the specified file upon startup. Note that +.B guacd +must have sufficient privileges to create or write this file, or it will fail +to start. This parameter is typically needed for startup scripts, such that the +script can report on the status of +.B guacd +and kill it if necessary. +. +.SH SSL PARAMETERS +If +.B guacd +was built SSL support, then connections between the web application and +.B guacd +can be encrypted if an SSL certificate and key file are given. +.P +When using a chain of certificates, you must append the additional certificates +to your server certificate. This can be done easily with the standard +.B cat +command. Beware that the certificate for +.B guacd +.I must +be the first certificate in the file. +.TP +\fBserver_certificate\fR \fB=\fR \fICERTIFICATE FILE\fR +Enables SSL/TLS using the given cerficiate file. Future connections to +.B guacd +will require SSL/TLS enabled in the client (the web application). +.TP +\fBserver_key\fR \fB=\fR \fIKEY FILE\fR +Enables SSL/TLS using the given private key file. Future connections to +.B guacd +will require SSL/TLS enabled in the client (the web application). +. +.SH EXAMPLE +.nf +.RS +# +# guacd.conf example +# + +[daemon] + +pid_file = /var/run/guacd.pid + +[server] + +bind_host = localhost +bind_port = 4822 + +[ssl] + +server_certificate = /etc/ssl/certs/guacd.crt +server_key = /etc/ssl/private/guacd.key +.RE +.fi +. +.SH AUTHOR +Written by Michael Jumper