summaryrefslogtreecommitdiff
path: root/doc/guix.texi
diff options
context:
space:
mode:
authorMaxim Cournoyer <maxim.cournoyer@gmail.com>2022-10-07 13:25:37 -0400
committerMaxim Cournoyer <maxim.cournoyer@gmail.com>2022-10-07 15:07:48 -0400
commit00e843050012961e9cc41b003ea9271eab718541 (patch)
treeb9d16bb2fc38b0d37c507bad9e5d1697b5aff1fd /doc/guix.texi
parent0c4966160054bc50e6ab3a4ac9c9a6a1826ab5a0 (diff)
Revert "Revert "services: Add xvnc-service-type.""
This reverts commit 0c4966160054bc50e6ab3a4ac9c9a6a1826ab5a0. The fix appears in the subsequent commit, for clarity.
Diffstat (limited to 'doc/guix.texi')
-rw-r--r--doc/guix.texi163
1 files changed, 159 insertions, 4 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index 27f63904cd..14592142dd 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17554,6 +17554,7 @@ declaration.
* Web Services:: Web servers.
* Certificate Services:: TLS certificates via Let's Encrypt.
* DNS Services:: DNS daemons.
+* VNC Services:: VNC daemons.
* VPN Services:: VPN daemons.
* Network File System:: NFS related services.
* Samba Services:: Samba services.
@@ -21062,6 +21063,7 @@ started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
@cindex GDM
@cindex GNOME, login manager
+@anchor{gdm}
GDM of course allows users to log in into window managers and desktop
environments other than GNOME; for those using GNOME, GDM is required for
features such as automatic screen locking.
@@ -21363,6 +21365,7 @@ Relogin after logout.
@cindex lightdm, graphical login manager
@cindex display manager, lightdm
+@anchor{lightdm}
@defvr {Scheme Variable} lightdm-service-type
This is the type of the service to run the
@url{https://github.com/canonical/lightdm,LightDM display manager}. Its
@@ -21566,10 +21569,11 @@ Extra configuration values to append to the seat configuration section.
@cindex Xorg, configuration
@deftp {Data Type} xorg-configuration
-This data type represents the configuration of the Xorg graphical display
-server. Note that there is no Xorg service; instead, the X server is started
-by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration
-of these display managers aggregates an @code{xorg-configuration} record.
+This data type represents the configuration of the Xorg graphical
+display server. Note that there is no Xorg service; instead, the X
+server is started by a ``display manager'' such as GDM, SDDM, LightDM or
+SLiM@. Thus, the configuration of these display managers aggregates an
+@code{xorg-configuration} record.
@table @asis
@item @code{modules} (default: @code{%default-xorg-modules})
@@ -30836,6 +30840,157 @@ Defaults to @samp{()}.
@c %end of fragment
+@node VNC Services
+@subsection VNC Services
+@cindex VNC (virtual network computing)
+@cindex XDMCP (x display manager control protocol)
+
+The @code{(gnu services vnc)} module provides services related to
+@dfn{Virtual Network Computing} (VNC), which makes it possible to
+locally use graphical Xorg applications running on a remote machine.
+Combined with a graphical manager that supports the @dfn{X Display
+Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM
+(@pxref{lightdm}), it is possible to remote an entire desktop for a
+multi-user environment.
+
+@subsubheading Xvnc
+
+Xvnc is a VNC server that spawns its own X window server; which means it
+can run on headless servers. The Xvnc implementations provided by the
+@code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
+
+@defvar {Scheme Variable} xvnc-service-type
+
+The @code{xvnc-server-type} service can be configured via the
+@code{xvnc-configuration} record, documented below. A second virtual
+display could be made available on a remote machine for via the
+following configuration:
+@end defvar
+
+@lisp
+(service xvnc-service-type (xvnc-configuration (display-number 10)
+@end lisp
+
+As a demonstration, the @command{xclock} command could then be started
+on the remote machine on display number 10, and it could be display
+locally via the @command{vncviewer} command:
+@example
+# Start xclock on the remote machine.
+ssh -L5910:localhost:5910 -- guix shell xclock -- env DISPLAY=:10 xclock
+# Access it via VNC.
+guix shell tigervnc-client -- vncviewer localhost:5910
+@end example
+
+The following configuration combines XDMCP and Inetd to allow multiple
+users to concurrently use the remote system, login in graphically via
+the GDM display manager:
+
+@lisp
+(operating-system
+ [...]
+ (services (cons*
+ [...]
+ (service xvnc-service-type (xvnc-configuration
+ (display-number 5)
+ (localhost? #f)
+ (xdmcp? #t)
+ (inetd? #t)))
+ (modify-services %desktop-services
+ (gdm-service-type config => (gdm-configuration
+ (inherit config)
+ (auto-suspend? #f)
+ (xdmcp? #t)))))))
+@end lisp
+
+A remote user could then connect to it by using the @command{vncviewer}
+command or a compatible VNC client and start a desktop session of their
+choosing:
+@example
+vncviewer remote-host:5905
+@end example
+
+@quotation Warning
+Unless your machine is in a controlled environment, for security
+reasons, the @code{localhost?} configuration of the
+@code{xvnc-configuration} record should be left to its default @code{#t}
+value and exposed via a secure means such as an SSH port forward. The
+XDMCP port, UDP 177 should also be blocked from the outside by a
+firewall, as it is not a secure protocol and can expose login
+credentials in clear.
+@end quotation
+
+@c Use (configuration->documentation 'xvnc-configuration) to regenerate
+@c the documentation.
+@c %start of fragment
+@deftp {Data Type} xvnc-configuration
+Available @code{xvnc-configuration} fields are:
+
+@table @asis
+@item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
+The package that provides the Xvnc binary.
+
+@item @code{display-number} (default: @code{0}) (type: number)
+The display number used by Xvnc. You should set this to a number not
+already used a Xorg server.
+
+@item @code{geometry} (default: @code{"1024x768"}) (type: string)
+The size of the desktop to be created.
+
+@item @code{depth} (default: @code{24}) (type: color-depth)
+The pixel depth in bits of the desktop to be created. Accepted values
+are 16, 24 or 32.
+
+@item @code{port} (type: maybe-port)
+The port on which to listen for connections from viewers. When left
+unspecified, it defaults to 5900 plus the display number.
+
+@item @code{ipv4?} (default: @code{#t}) (type: boolean)
+Use IPv4 for incoming and outgoing connections.
+
+@item @code{ipv6?} (default: @code{#t}) (type: boolean)
+Use IPv6 for incoming and outgoing connections.
+
+@item @code{password-file} (type: maybe-string)
+The password file to use, if any. Refer to vncpasswd(1) to learn how to
+generate such a file.
+
+@item @code{xdmcp?} (default: @code{#f}) (type: boolean)
+Query the XDMCP server for a session. This enables users to log in a
+desktop session from the login manager screen. For a multiple users
+scenario, you'll want to enable the @code{inetd?} option as well, so
+that each connection to the VNC server is handled separately rather than
+shared.
+
+@item @code{inetd?} (default: @code{#f}) (type: boolean)
+Use an Inetd-style service, which runs the Xvnc server on demand.
+
+@item @code{frame-rate} (default: @code{60}) (type: number)
+The maximum number of updates per second sent to each client.
+
+@item @code{security-types} (default: @code{("None")}) (type: security-types)
+The allowed security schemes to use for incoming connections. The
+default is "None", which is safe given that Xvnc is configured to
+authenticate the user via the display manager, and only for local
+connections. Accepted values are any of the following: ("None"
+"VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc")
+
+@item @code{localhost?} (default: @code{#t}) (type: boolean)
+Only allow connections from the same machine. It is set to #true by
+default for security, which means SSH or another secure means should be
+used to expose the remote port.
+
+@item @code{log-level} (default: @code{30}) (type: log-level)
+The log level, a number between 0 and 100, 100 meaning most verbose
+output. The log messages are output to syslog.
+
+@item @code{extra-options} (default: @code{()}) (type: strings)
+This can be used to provide extra Xvnc options not exposed via this
+<xvnc-configuration> record.
+
+@end table
+
+@end deftp
+@c %end of fragment
@node VPN Services
@subsection VPN Services