From ebb2026a7cb5295986397955c1661322fb13963d Mon Sep 17 00:00:00 2001 From: Mike Gabriel Date: Tue, 5 Jul 2016 13:24:16 +0200 Subject: man pages: Greatly improve man pages nxagent.1 and nxproxy.1. --- nx-X11/programs/Xserver/hw/nxagent/man/nxagent.1 | 997 ++++++++++++++++++++++- nxproxy/man/nxproxy.1 | 380 ++++++++- 2 files changed, 1347 insertions(+), 30 deletions(-) diff --git a/nx-X11/programs/Xserver/hw/nxagent/man/nxagent.1 b/nx-X11/programs/Xserver/hw/nxagent/man/nxagent.1 index f92393893..a97204afe 100644 --- a/nx-X11/programs/Xserver/hw/nxagent/man/nxagent.1 +++ b/nx-X11/programs/Xserver/hw/nxagent/man/nxagent.1 @@ -1,37 +1,992 @@ -.TH NXAGENT 1 + +.\" Copyright 1984 - 1991, 1993, 1994, 1998 The Open Group +.\" Copyright 2011 - 2016, Mike Gabriel +.\" +.\" Permission to use, copy, modify, distribute, and sell this software and its +.\" documentation for any purpose is hereby granted without fee, provided that +.\" the above copyright notice appear in all copies and that both that +.\" copyright notice and this permission notice appear in supporting +.\" documentation. +.\" +.\" The above copyright notice and this permission notice shall be included +.\" in all copies or substantial portions of the Software. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +.\" IN NO EVENT SHALL THE OPEN GROUP BE LIABLE FOR ANY CLAIM, DAMAGES OR +.\" OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, +.\" ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +.\" OTHER DEALINGS IN THE SOFTWARE. +.\" +.\" Except as contained in this notice, the name of The Open Group shall +.\" not be used in advertising or otherwise to promote the sale, use or +.\" other dealings in this Software without prior written authorization +.\" from The Open Group. +.ds q \N'34' +.TH NXAGENT 1 3.6.x .SH NAME -nxagent \- NoMachine's NX Agent. +nxagent \- nx-X11 Agent (nested Xserver optimized for remote computing) .SH SYNOPSIS .B nxagent .I "[options]" - .SH DESCRIPTION \fBnxagent\fR is an Xnest-like X server for remote application/desktop access. .PP -\fBnxagent\fR implements a very efficient compression of the X11 protocol. +\fBnxagent\fR implements a very efficient compression of the X11 +protocol, called the NX protocol. +.PP +The NX protocol increases performance when using X applications over high +latency and low bandwidth networks, while providing a local (LAN-like) +usage experience even if connecting from off-site locations (via cable +modem or GSM). +.PP +\fBnxagent\fR can be used standalone as a nested X server (with NX +protocol disabled), but its real benefits are gained when using it over +remote connections via the nxcomp compression library. The counterpart +application on the other end (i.e. the client) is called +\fBnxproxy\fR. .PP -This increases performance when using X applications over high latency and -low bandwidth networks, while providing a local (LAN-like) usage experience -even if connecting from off-site locations (via cable modem or GSM). +When used in proxy <-> agent mode, \fBnxagent\fR adds the feature of +being suspendible. Sessions can be started from one client, suspended and +then resumed from another client. .PP -\fBnxagent\fR is not designed to be used as a standalone application. -It has to be launched on the server side by remote desktop frameworks like FreeNX. +\fBnxagent\fR and \fBnxproxy\fR are utilized by various remote +application/desktop frameworks for providing server-side GUI application +access from remote client systems. +.PP +Currently, nx-X11 Agent is co-maintained by three of these projects: The +Arctica Project, TheQVD and X2Go. .PP -Available clients are -NoMachine's \fBnxclient\fR or the community projects \fBqtnx\fR and \fBremmina\fR -(with NX plugin). + +.SH "STARTING THE SERVER" +The nx-X11 Agent should be run in user space. Other than the system's +local X.org server, \fBnxagent\fR does not require to be run as root. +When bundled with a remote application framework, you normally don't have +to launch \fBnxagent\fR manually. nx-X11 Agent startup is normally +managed by the underlying framework (e.g. Arctica Session Manager, X2Go +Server, etc.). +.PP +When the nx-X11 Agent starts up (e.g. by typing 'nxagent -ac :1' in a +terminal window), it typically launches in "windowed desktop" mode. On +your local X server, there appears a new window being an X server itself. +.PP +However, nx-X11 Agent also supports rootless (or seamless) application +mode and a shadow session mode (similar to what VNC does). +.PP +Example: You can launch a complete desktop session inside this nested X +server now: +.TP 8 +The Debian way... +.PP +.nf + $ export DISPLAY=:1 + $ STARTUP=mate-session /etc/X11/Xsession +.fi +.TP 8 +The Fedora / Gentoo / openSUSE way... +.PP +.nf + ### FIXME / TODO ### +.fi +.PP +However, nx-X11 Agent also supports rootless (or seamless) application +mode and a shadow session mode (similar to what VNC does). .SH OPTIONS -.TP +The nx-X11 agent accepts a range of default X server options as described +below. Those default options have to be provided via the command line. + +Furthermore, the nx-X11 Agent accepts some nx-X11 specific options, +described further below. + +Last but not least, the nx-X11 Agent accepts several more options +provided via the $DISPLAY environment variable, the so-called nx/nx +options. See below for further details. + +.SH STANDARD XSERVER OPTIONS +.TP 8 +.B :\fIdisplaynumber\fP +The X server runs as the given \fIdisplaynumber\fP, which by default is 0. +If multiple X servers are to run simultaneously on a host, each must have +a unique display number. See the DISPLAY +NAMES section of the \fIX\fP(__miscmansuffix__) manual page to learn how to +specify which display number clients should try to use. +.TP 8 +.B \-a \fInumber\fP +sets pointer acceleration (i.e. the ratio of how much is reported to how much +the user actually moved the pointer). +.TP 8 +.B \-ac +disables host-based access control mechanisms. Enables access by any host, +and permits any host to modify the access control list. +Use with extreme caution. +This option exists primarily for running test suites remotely. +.TP 8 +.B \-audit \fIlevel\fP +sets the audit trail level. The default level is 1, meaning only connection +rejections are reported. Level 2 additionally reports all successful +connections and disconnects. Level 4 enables messages from the +SECURITY extension, if present, including generation and revocation of +authorizations and violations of the security policy. +Level 0 turns off the audit trail. +Audit lines are sent as standard error output. +.TP 8 +.B \-auth \fIauthorization-file\fP +specifies a file which contains a collection of authorization records used +to authenticate access. See also the \fIxdm\fP(1) and +\fIXsecurity\fP(__miscmansuffix__) manual pages. +.TP 8 +.B bc +disables certain kinds of error checking, for bug compatibility with +previous releases (e.g., to work around bugs in R2 and R3 xterms and toolkits). +Deprecated. +.TP 8 +.B \-bs +disables backing store support on all screens. +.TP 8 +.B \-br +sets the default root window to solid black instead of the standard root weave +pattern. +.TP 8 +.B \-c +turns off key-click. +.TP 8 +.B c \fIvolume\fP +sets key-click volume (allowable range: 0-100). +.TP 8 +.B \-cc \fIclass\fP +sets the visual class for the root window of color screens. +The class numbers are as specified in the X protocol. +Not obeyed by all servers. +.TP 8 +.B \-co \fIfilename\fP +sets name of RGB color database. The default is +.IR /usr/share/nx/rgb . +.ig +.TP 8 +.B \-config \fIfilename\fP +reads more options from the given file. Options in the file may be separated +by newlines if desired. If a '#' character appears on a line, all characters +between it and the next newline are ignored, providing a simple commenting +facility. The \fB\-config\fP option itself may appear in the file. +.BR NOTE : +This option is disabled when the Xserver is run with an effective uid +different from the user's real uid. +.. +.TP 8 +.B \-core +causes the server to generate a core dump on fatal errors. +.TP 8 +.B \-deferglyphs \fIwhichfonts\fP +specifies the types of fonts for which the server should attempt to use +deferred glyph loading. \fIwhichfonts\fP can be all (all fonts), +none (no fonts), or 16 (16 bit fonts only). +.TP 8 +.B \-dpi \fIresolution\fP +sets the resolution for all screens, in dots per inch. +To be used when the server cannot determine the screen size(s) from the +hardware. +.TP 8 +.B dpms +enables DPMS (display power management services), where supported. The +default state is platform and configuration specific. +.TP 8 +.B \-dpms +disables DPMS (display power management services). The default state +is platform and configuration specific. +.TP 8 +.B \-f \fIvolume\fP +sets feep (bell) volume (allowable range: 0-100). +.TP 8 +.B \-fc \fIcursorFont\fP +sets default cursor font. +.TP 8 +.B \-fn \fIfont\fP +sets the default font. +.TP 8 +.B \-fp \fIfontPath\fP +sets the search path for fonts. This path is a comma separated list +of directories which the X server searches for font databases. +See the FONTS section of this manual page for more information and the default +list. +.TP 8 .B \-help -Lists all others options that are not listed here. +prints a usage message. +.TP 8 +.B \-I +causes all remaining command line arguments to be ignored. +.TP 8 +.B \-maxbigreqsize \fIsize\fP +sets the maxmium big request to +.I size +MB. +.TP 8 +.B \-nolisten \fItrans-type\fP +disables a transport type. For example, TCP/IP connections can be disabled +with +.BR "\-nolisten tcp" . +This option may be issued multiple times to disable listening to different +transport types. +.TP 8 +.B \-noreset +prevents a server reset when the last client connection is closed. This +overrides a previous +.B \-terminate +command line option. +.TP 8 +.B \-p \fIminutes\fP +sets screen-saver pattern cycle time in minutes. +.TP 8 +.B \-pn +permits the server to continue running if it fails to establish all of +its well-known sockets (connection points for clients), but +establishes at least one. This option is set by default. +.TP 8 +.B \-nopn +causes the server to exit if it fails to establish all of its well-known +sockets (connection points for clients). +.TP 8 +.B \-r +turns off auto-repeat. +.TP 8 +.B r +turns on auto-repeat. +.TP 8 +.B \-s \fIminutes\fP +sets screen-saver timeout time in minutes. +.TP 8 +.B \-su +disables save under support on all screens. +.TP 8 +.B \-t \fInumber\fP +sets pointer acceleration threshold in pixels (i.e. after how many pixels +pointer acceleration should take effect). +.TP 8 +.B \-terminate +causes the server to terminate at server reset, instead of continuing to run. +This overrides a previous +.B \-noreset +command line option. +.TP 8 +.B \-to \fIseconds\fP +sets default connection timeout in seconds. +.TP 8 +.B \-tst +disables all testing extensions (e.g., XTEST, XTrap, XTestExtension1, RECORD). +.TP 8 +.B tty\fIxx\fP +ignored, for servers started the ancient way (from init). +.TP 8 +.B v +sets video-off screen-saver preference. +.TP 8 +.B \-v +sets video-on screen-saver preference. +.TP 8 +.B \-wm +forces the default backing-store of all windows to be WhenMapped. This +is a backdoor way of getting backing-store to apply to all windows. +Although all mapped windows will have backing store, the backing store +attribute value reported by the server for a window will be the last +value established by a client. If it has never been set by a client, +the server will report the default value, NotUseful. This behavior is +required by the X protocol, which allows the server to exceed the +client's backing store expectations but does not provide a way to tell +the client that it is doing so. +.TP 8 +.B \-x \fIextension\fP +loads the specified extension at init. +This is a no-op for most implementations. +.TP 8 +.B [+-]xinerama +enables(+) or disables(-) XINERAMA provided via the PanoramiX extension. This is +set to off by default. +.TP 8 +.B [+-]rrxinerama +enables(+) or disables(-) XINERAMA provided via the RandR extension. By +default, this feature is enabled. To disable XINERAMA completely, make +sure to use both options (-xinerama -rrxinerama) on the command line. + +.SH SERVER DEPENDENT OPTIONS +The nx-X11 Xserver (i.e. \fBnxagent\fR) additionally accepts the following options (non-standard options, dependent on Xserver implementation): +.TP 8 +.B \-logo +turns on the X Window System logo display in the screen-saver. +There is currently no way to change this from a client. +.TP 8 +.B nologo +turns off the X Window System logo display in the screen-saver. +There is currently no way to change this from a client. +.TP 8 +.B \-render +.BR default | mono | gray | color +sets the color allocation policy that will be used by the render extension. +.RS 8 +.TP 8 +.I default +selects the default policy defined for the display depth of the X +server. +.TP 8 +.I mono +don't use any color cell. +.TP 8 +.I gray +use a gray map of 13 color cells for the X render extension. +.TP 8 +.I color +use a color cube of at most 4*4*4 colors (that is 64 color cells). +.RE +.TP 8 +.B \-dumbSched +disables smart scheduling on platforms that support the smart scheduler. +.TP +.B \-schedInterval \fIinterval\fP +sets the smart scheduler's scheduling interval to +.I interval +milliseconds. +.SH NXAGENT SPECIFIC OPTIONS +The nx-X11 system adds the following command line arguments: +.TP 8 +.B \-forcenx +force use of NX protocol messages assuming communication through nxproxy +.TP 8 +.B \-timeout \fIint\fP +auto-disconnect timeout in seconds (minimum allowed: 60) +.TP 8 +.B \-norootlessexit +don't exit if there are no clients in rootless mode +.TP 8 +.B \-norender +disable the use of the render extension +.TP 8 +.B \-nocomposite +disable the use of the composite extension +.TP 8 +.B \-nopersistent +disable disconnection/reconnection to the X display on SIGHUP +.TP 8 +.B \-noshmem +disable use of shared memory extension +.TP 8 +.B \-shmem +enable use of shared memory extension +.TP 8 +.B \-noshpix +disable use of shared pixmaps +.TP 8 +.B \-shpix +enable use of shared pixmaps +.TP 8 +.B \-noignore +don't ignore pointer and keyboard configuration changes mandated by clients +.TP 8 +.B \-nokbreset +don't reset keyboard device if the session is resumed +.TP 8 +.B \-noxkblock +always allow applications to change layout through XKEYBOARD +.TP 8 +.B \-tile WxH +size of image tiles (minimum allowed: 32x32) +.TP 8 +.B \-D +enable desktop mode (default) +.TP 8 +.B \-R +enable rootless mode +.TP 8 +.B \-S +enable shadow mode +.TP 8 +.B \-B +enable proxy binding mode +.PP +Other than the command line options, \fBnxagent\fR can be configured at +session startup and at runtime (i.e. when resuming a suspended session) +by so-called nx/nx options. +.PP +As nx/nx options all options supported by nxcomp (see \fBnxproxy\fR man +page) and all nxagent nx/nx options (see below) can be used. +. +When launching an nxcomp based nx-X11 agent session (i.e. proxy <-> +agent), you will normally set the $DISPLAY variable like this: +.PP +.nf + $ export DISPLAY=nx/nx,listen=,options=: + $ nxagent : +.fi +.PP +The value for is some value of a not-yet-used X11 +display (e.g. :50). +.PP +Using an options file is recommended, but you can also put available +nx/nx options (see below) into the DISPLAY variable directly. Note, that +the $DISPLAY variable field is of limited length. +.PP +As you can pick an arbitrary (unused) TCP port or Unix +socket file path. This is the port / socket that you have to connect to +with the \fBnxproxy\fR application. +.PP +Available nx-X11 Agent options (as an addition to nx/nx options supported +by nxcomp already): +.TP 8 +.B options= +read options from file, this text file can contain a single loooong line with comma-separated nx/nx options +.TP 8 +.B rootless= +start \fBnxagent\fR in rootless mode, matches \-R given on the command line, no-op when resuming (default: false) +.TP 8 +.B geometry= +desktop geometry when starting or resuming a session, no-op in rootless mode (default 66% of the underlying X server geometry) +.TP 8 +.B resize= +set resizing support (default: true) +.TP 8 +.B fullscreen= +start or resume a session in fullscreen mode (default: off) +.TP 8 +.B keyboard= +set remote keyboard layout +.TP 8 +.B clipboard= +enable / disable (set to: \fInone\fR) clipboard support, uni-directional (\fIserver\fR or \fIclient\fR) or bi-directional (\fIboth\fR, default setting) support +.TP 8 +.B streaming= +streaming support for images, not fully implemented yet and thus non-functional +.TP 8 +.B backingstore= +disable or enforce backing store support (default: BackingStoreUndefined) +.TP 8 +.B composite= +enable or disable Compsite support in \fBnxagent\fR (default: enabled) +.TP 8 +.B xinerama= +enable or disable XINERAMA support in \fBnxagent\fR (default: enabled) +.TP 8 +.B shmem= +enable using shared memory +.TP 8 +.B shpix= +enable shared pixmaps support +.TP 8 +.B kbtype= +set remote keyboard type +.TP 8 +.B client= +type of connecting operating system (supported: \fIlinux\fR, \fIwindows\fR, \fIsolaris\fR and \fImacosx\fR) +.TP 8 +.B shadow= +start \fBnxagent\fR in shadow mode, matches \-S given on the command line, no-op when resuming (default: false) +.TP 8 +.B shadowuid= +unique identifier for the shadow session +.TP 8 +.B shadowmode= +full access (set to \fI1\fR) or viewing-only (set to \fI0\fR, default) +.TP 8 +.B defer= +defer image updates (enabled for all connection types except LAN), accepts values \fI0\fR, \fI1\fR and \fI2\fR + +The default value can be set via the cmd line (\-defer). The value +provided as nx/nx option is set when resuming a session, thus it +overrides the cmd line default. +.TP 8 +.B tile= +set the tile size in pixels (\fIx\fR) for bitmap data sent over the wire + +The default value can be set via the cmd line (\-tile). The value +provided as nx/nx option is set when resuming a session, thus it +overrides the cmd line default. +.TP 8 +.B menu= +support pulldown menu in nx-X11 Agent session (only available on proxy <-> agent remote sessions) +.TP 8 +.B sleep= +delay X server operations when suspended (provided in msec), set to \fI0\fR to keep nx-X11 Agent session +fully functional when suspended (e.g. useful when mirroring nx-X11 Agent session via VNC) + +.SH XDMCP OPTIONS +X servers that support XDMCP have the following options. +See the \fIX Display Manager Control Protocol\fP specification for more +information. +.TP 8 +.B \-query \fIhostname\fP +enables XDMCP and sends Query packets to the specified +.IR hostname . +.TP 8 +.B \-broadcast +enable XDMCP and broadcasts BroadcastQuery packets to the network. The +first responding display manager will be chosen for the session. +.TP 8 +.B \-multicast [\fIaddress\fP [\fIhop count\fP]] +Enable XDMCP and multicast BroadcastQuery packets to the network. +The first responding display manager is chosen for the session. If an +address is specified, the multicast is sent to that address. If no +address is specified, the multicast is sent to the default XDMCP IPv6 +multicast group. If a hop count is specified, it is used as the maximum +hop count for the multicast. If no hop count is specified, the multicast +is set to a maximum of 1 hop, to prevent the multicast from being routed +beyond the local network. +.TP 8 +.B \-indirect \fIhostname\fP +enables XDMCP and send IndirectQuery packets to the specified +.IR hostname . +.TP 8 +.B \-port \fIport-number\fP +uses the specified \fIport-number\fP for XDMCP packets, instead of the +default. This option must be specified before any \-query, \-broadcast, +\-multicast, or \-indirect options. +.TP 8 +.B \-from \fIlocal-address\fP +specifies the local address to connect from (useful if the connecting host +has multiple network interfaces). The \fIlocal-address\fP may be expressed +in any form acceptable to the host platform's \fIgethostbyname\fP(3) +implementation. +.TP 8 +.B \-once +causes the server to terminate (rather than reset) when the XDMCP session +ends. +.TP 8 +.B \-class \fIdisplay-class\fP +XDMCP has an additional display qualifier used in resource lookup for +display-specific options. This option sets that value, by default it +is "MIT-Unspecified" (not a very useful value). +.TP 8 +.B \-cookie \fIxdm-auth-bits\fP +When testing XDM-AUTHENTICATION-1, a private key is shared between the +server and the manager. This option sets the value of that private +data (not that it is very private, being on the command line!). +.TP 8 +.B \-displayID \fIdisplay-id\fP +Yet another XDMCP specific value, this one allows the display manager to +identify each display so that it can locate the shared key. + +.SH XKEYBOARD OPTIONS +X servers that support the XKEYBOARD (a.k.a. \*qXKB\*q) extension accept the +following options. All layout files specified on the command line must be +located in the XKB base directory or a subdirectory, and specified as the +relative path from the XKB base directory. The default XKB base directory is +.IR /usr/share/X11/xkb . +.TP 8 +.B [+-]kb +enables(+) or disables(-) the XKEYBOARD extension. +.TP 8 +.BR [+-]accessx " [ \fItimeout\fP [ \fItimeout_mask\fP [ \fIfeedback\fP [ \fIoptions_mask\fP ] ] ] ]" +enables(+) or disables(-) AccessX key sequences. +.TP 8 +.B \-xkbdir \fIdirectory\fP +base directory for keyboard layout files. This option is not available +for setuid X servers (i.e., when the X server's real and effective uids +are different). +.TP 8 +.B \-ar1 \fImilliseconds\fP +sets the autorepeat delay (length of time in milliseconds that a key must +be depressed before autorepeat starts). +.TP 8 +.B \-ar2 \fImilliseconds\fP +sets the autorepeat interval (length of time in milliseconds that should +elapse between autorepeat-generated keystrokes). +.TP 8 +.B \-noloadxkb +disables loading of an XKB keymap description on server startup. +.TP 8 +.B \-xkbdb \fIfilename\fP +uses \fIfilename\fP for default keyboard keymaps. +.TP 8 +.B \-xkbmap \fIfilename\fP +loads keyboard description in \fIfilename\fP on server startup. + +.SH SECURITY EXTENSION OPTIONS +X servers that support the SECURITY extension accept the following option: +.TP 8 +.B \-sp \fIfilename\fP +causes the server to attempt to read and interpret filename as a security +policy file with the format described below. The file is read at server +startup and reread at each server reset. +.PP +The syntax of the security policy file is as follows. +Notation: "*" means zero or more occurrences of the preceding element, +and "+" means one or more occurrences. To interpret , ignore +the text after the /; it is used to distinguish between instances of + in the next section. +.PP +.nf + ::= * + + ::= '\en' + + ::= | | | + + ::= # * '\en' + + ::= '\en' + + ::= sitepolicy '\en' + + ::= property '\en' + + ::= + + ::= any | root | + + ::= | + + ::= = + + ::= [ | | ]* + + ::= r | w | d + + ::= a | i | e + + ::= | | + + ::= " * " + + ::= ' * ' + + ::= + -.SH FURTHER READINGS -Information on NX: http://www.nomachine.com + ::= [ ' ' | '\et' ]* + +Character sets: + + ::= any character except '\en' + ::= any character except " + ::= any character except ' + ::= any character except those in +.fi +.PP +The semantics associated with the above syntax are as follows. +.PP +, the first line in the file, specifies the file format +version. If the server does not recognize the version , it +ignores the rest of the file. The version string for the file format +described here is "version-1" . +.PP +Once past the , lines that do not match the above syntax +are ignored. +.PP + lines are ignored. +.PP + lines are currently ignored. They are intended to +specify the site policies used by the XC-QUERY-SECURITY-1 +authorization method. +.PP + lines specify how the server should react to untrusted +client requests that affect the X Window property named . +The rest of this section describes the interpretation of an +. +.PP +For an to apply to a given instance of , + must be on a window that is in the set of windows +specified by . If is any, the rule applies to + on any window. If is root, the rule applies to + only on root windows. +.PP +If is , the following apply. If is a , the rule applies when the window also +has that , regardless of its value. If is a , must also have +the value specified by . In this case, the property must +have type STRING and format 8, and should contain one or more +null-terminated strings. If any of the strings match , the +rule applies. +.PP +The definition of string matching is simple case-sensitive string +comparison with one elaboration: the occurrence of the character '*' in + is a wildcard meaning "any string." A can +contain multiple wildcards anywhere in the string. For example, "x*" +matches strings that begin with x, "*x" matches strings that end with +x, "*x*" matches strings containing x, and "x*y*" matches strings that +start with x and subsequently contain y. +.PP +There may be multiple lines for a given . +The rules are tested in the order that they appear in the file. The +first rule that applies is used. +.PP + specify operations that untrusted clients may attempt, and +the actions that the server should take in response to those operations. +.PP + can be r (read), w (write), or d (delete). The following +table shows how X Protocol property requests map to these operations +in The Open Group server implementation. +.PP +.nf +GetProperty r, or r and d if delete = True +ChangeProperty w +RotateProperties r and w +DeleteProperty d +ListProperties none, untrusted clients can always list all properties +.fi +.PP + can be a (allow), i (ignore), or e (error). Allow means +execute the request as if it had been issued by a trusted client. +Ignore means treat the request as a no-op. In the case of +GetProperty, ignore means return an empty property value if the +property exists, regardless of its actual value. Error means do not +execute the request and return a BadAtom error with the atom set to +the property name. Error is the default action for all properties, +including those not listed in the security policy file. +.PP +An applies to all s that follow it, until the next + is encountered. Thus, irwad means ignore read and write, +allow delete. +.PP +GetProperty and RotateProperties may do multiple operations (r and d, +or r and w). If different actions apply to the operations, the most +severe action is applied to the whole request; there is no partial +request execution. The severity ordering is: allow < ignore < error. +Thus, if the for a property are ired (ignore read, error +delete), and an untrusted client attempts GetProperty on that property +with delete = True, an error is returned, but the property value is +not. Similarly, if any of the properties in a RotateProperties do not +allow both read and write, an error is returned without changing any +property values. +.PP +Here is an example security policy file. +.PP +.ta 3i 4i +.nf +version-1 + +# Allow reading of application resources, but not writing. +property RESOURCE_MANAGER root ar iw +property SCREEN_RESOURCES root ar iw + +# Ignore attempts to use cut buffers. Giving errors causes apps to crash, +# and allowing access may give away too much information. +property CUT_BUFFER0 root irw +property CUT_BUFFER1 root irw +property CUT_BUFFER2 root irw +property CUT_BUFFER3 root irw +property CUT_BUFFER4 root irw +property CUT_BUFFER5 root irw +property CUT_BUFFER6 root irw +property CUT_BUFFER7 root irw + +# If you are using Motif, you probably want these. +property _MOTIF_DEFAULT_BINDINGS root ar iw +property _MOTIF_DRAG_WINDOW root ar iw +property _MOTIF_DRAG_TARGETS any ar iw +property _MOTIF_DRAG_ATOMS any ar iw +property _MOTIF_DRAG_ATOM_PAIRS any ar iw + +# The next two rules let xwininfo -tree work when untrusted. +property WM_NAME any ar + +# Allow read of WM_CLASS, but only for windows with WM_NAME. +# This might be more restrictive than necessary, but demonstrates +# the facility, and is also an attempt to +# say "top level windows only." +property WM_CLASS WM_NAME ar + +# These next three let xlsclients work untrusted. Think carefully +# before including these; giving away the client machine name and command +# may be exposing too much. +property WM_STATE WM_NAME ar +property WM_CLIENT_MACHINE WM_NAME ar +property WM_COMMAND WM_NAME ar + +# To let untrusted clients use the standard colormaps created by +# xstdcmap, include these lines. +property RGB_DEFAULT_MAP root ar +property RGB_BEST_MAP root ar +property RGB_RED_MAP root ar +property RGB_GREEN_MAP root ar +property RGB_BLUE_MAP root ar +property RGB_GRAY_MAP root ar + +# To let untrusted clients use the color management database created +# by xcmsdb, include these lines. +property XDCCC_LINEAR_RGB_CORRECTION root ar +property XDCCC_LINEAR_RGB_MATRICES root ar +property XDCCC_GRAY_SCREENWHITEPOINT root ar +property XDCCC_GRAY_CORRECTION root ar + +# To let untrusted clients use the overlay visuals that many vendors +# support, include this line. +property SERVER_OVERLAY_VISUALS root ar + +# Dumb examples to show other capabilities. + +# oddball property names and explicit specification of error conditions +property "property with spaces" 'property with "' aw er ed + +# Allow deletion of Woo-Hoo if window also has property OhBoy with value +# ending in "son". Reads and writes will cause an error. +property Woo-Hoo OhBoy = "*son" ad + +.fi +.SH "NETWORK CONNECTIONS" +The X server supports client connections via a platform-dependent subset of +the following transport types: TCP\/IP, Unix Domain sockets, DECnet, +and several varieties of SVR4 local connections. See the DISPLAY +NAMES section of the \fIX\fP(__miscmansuffix__) manual page to learn how to +specify which transport type clients should try to use. + +.SH GRANTING ACCESS +The X server implements a platform-dependent subset of the following +authorization protocols: MIT-MAGIC-COOKIE-1, XDM-AUTHORIZATION-1, +XDM-AUTHORIZATION-2, SUN-DES-1, and MIT-KERBEROS-5. See the +\fIXsecurity\fP(__miscmansuffix__) manual page for information on the +operation of these protocols. +.PP +Authorization data required by the above protocols is passed to the +server in a private file named with the \fB\-auth\fP command line +option. Each time the server is about to accept the first connection +after a reset (or when the server is starting), it reads this file. +If this file contains any authorization records, the local host is not +automatically allowed access to the server, and only clients which +send one of the authorization records contained in the file in the +connection setup information will be allowed access. See the +\fIXau\fP manual page for a description of the binary format of this +file. See \fIxauth\fP(1) for maintenance of this file, and distribution +of its contents to remote hosts. +.PP +The X server also uses a host-based access control list for deciding +whether or not to accept connections from clients on a particular machine. +If no other authorization mechanism is being used, +this list initially consists of the host on which the server is running as +well as any machines listed in the file \fI/etc/X\fBn\fI.hosts\fR, where +\fBn\fP is the display number of the server. Each line of the file should +contain either an Internet hostname (e.g. expo.lcs.mit.edu) or a DECnet +hostname in double colon format (e.g. hydra::) or a complete name in the format +\fIfamily\fP:\fIname\fP as described in the \fIxhost\fP(1) manual page. +There should be no leading or trailing spaces on any lines. For example: +.sp +.in +8 +.nf +joesworkstation +corporate.company.com +star:: +inet:bigcpu +local: +.fi +.in -8 +.PP +Users can add or remove hosts from this list and enable or disable access +control using the \fIxhost\fP command from the same machine as the server. +.PP +If the X FireWall Proxy (\fIxfwp\fP) is being used without a sitepolicy, +host-based authorization must be turned on for clients to be able to +connect to the X server via the \fIxfwp\fP. If \fIxfwp\fP is run without +a configuration file and thus no sitepolicy is defined, if \fIxfwp\fP +is using an X server where xhost + has been run to turn off host-based +authorization checks, when a client tries to connect to this X server +via \fIxfwp\fP, the X server will deny the connection. See \fIxfwp\fP(1) +for more information about this proxy. +.PP +The X protocol intrinsically does not have any notion of window operation +permissions or place any restrictions on what a client can do; if a program can +connect to a display, it has full run of the screen. +X servers that support the SECURITY extension fare better because clients +can be designated untrusted via the authorization they use to connect; see +the \fIxauth\fP(1) manual page for details. Restrictions are imposed +on untrusted clients that curtail the mischief they can do. See the SECURITY +extension specification for a complete list of these restrictions. +.PP +Sites that have better +authentication and authorization systems might wish to make +use of the hooks in the libraries and the server to provide additional +security models. +.SH SIGNALS +The X server attaches special meaning to the following signals: +.TP 8 +.I SIGHUP +This signal causes the server to close all existing connections, free all +resources, and restore all defaults. It is sent by the display manager +whenever the main user's main application (usually an \fIxterm\fP or window +manager) exits to force the server to clean up and prepare for the next +user. +.TP 8 +.I SIGTERM +This signal causes the server to exit cleanly. +.TP 8 +.I SIGUSR1 +This signal is used quite differently from either of the above. When the +server starts, it checks to see if it has inherited SIGUSR1 as SIG_IGN +instead of the usual SIG_DFL. In this case, the server sends a SIGUSR1 to +its parent process after it has set up the various connection schemes. +\fIXdm\fP uses this feature to recognize when connecting to the server +is possible. +.SH FONTS +The X server +can obtain fonts from directories and/or from font servers. +The list of directories and font servers +the X server uses when trying to open a font is controlled +by the \fIfont path\fP. +.LP +The default font path is +__default_font_path__ . +.LP +The font path can be set with the \fB\-fp\fP option or by \fIxset\fP(1) +after the server has started. +.SH FILES +.TP 30 +.I /etc/X\fBn\fP.hosts +Initial access control list for display number \fBn\fP +.TP 30 +.IR /usr/share/fonts/X11/misc, + /usr/share/fonts/X11/75dpi, + /usr/share/fonts/X11/100dpi +Bitmap font directories +.TP 30 +.IR /usr/share/fonts/X11/Type1 +Outline font directories +.TP 30 +.I /usr/share/nx/rgb +Color database +.TP 30 +.I /tmp/.X11-unix/X\fBn\fP +Unix domain socket for display number \fBn\fP +.TP 30 +.IR /tmp/rcX\fBn\fP +Kerberos 5 replay cache for display number \fBn\fP +.SH "SEE ALSO" +Protocols: +.I "X Window System Protocol," +.I "NX Compression Protocol," +.I "The X Font Service Protocol," +.I "X Display Manager Control Protocol" +.PP +Fonts: \fIbdftopcf\fP(1), \fImkfontdir\fP(1), \fImkfontscale\fP(1), +\fIxfs\fP(1), \fIxlsfonts\fP(1), \fIxfontsel\fP(1), \fIxfd\fP(1), +.I "X Logical Font Description Conventions" +.PP +Security: \fIXsecurity\fP(__miscmansuffix__), \fIxauth\fP(1), \fIXau\fP(1), +\fIxdm\fP(1), \fIxhost\fP(1), \fIxfwp\fP(1), +.I "Security Extension Specification" +.PP +Starting the server: \fIxdm\fP(1), \fIxinit\fP(1) +.PP +Controlling the server once started: \fIxset\fP(1), \fIxsetroot\fP(1), +\fIxhost\fP(1) +.PP +Server-specific man pages: +\fIXdec\fP(1), \fIXmacII\fP(1), \fIXsun\fP(1), \fIXnest\fP(1), +\fIXvfb\fP(1), \fIXFree86\fP(1), \fIXDarwin\fP(1). +.PP +Server internal documentation: +.I "Definition of the Porting Layer for the X v11 Sample Server" +.SH AUTHORS +The first sample X server was originally written by Susan Angebranndt, +Raymond Drewry, Philip Karlton, and Todd Newman, from Digital Equipment +Corporation, with support from a large cast. It has since been +extensively rewritten by Keith Packard and Bob Scheifler, from MIT. Dave +Wiggins took over post-R5 and made substantial improvements. +.PP +The first implementation of nx-X11 (version 1.x up to 3.5.x) was written +by NoMachine (maintained until 2011). +.PP +The current implementation of nx-X11 is maintained by various projects, +amongst others The Arctica Project, TheQVD (Qindel Group) and X2Go. .PP -Information on FreeNX: http://freenx.berlios.de +This manual page was written by Per Hansen , and +modified by Marcelo Boveto Shima and Mike +Gabriel . In 2016, the original +Xserver.man page shipped with nx-X11 was merged into the \fBnxagent\fR +man page and received a major update by Mike Gabriel +. -.SH AUTHOR -This manual page was written by Per Hansen , -and modified by Marcelo Boveto Shima and -Mike Gabriel . diff --git a/nxproxy/man/nxproxy.1 b/nxproxy/man/nxproxy.1 index d389d1068..6922c1427 100644 --- a/nxproxy/man/nxproxy.1 +++ b/nxproxy/man/nxproxy.1 @@ -5,23 +5,385 @@ \\$2 \(la\\$1\(ra\\$3 .. .if \n(.g .mso www.tmac -.TH nxproxy 1 "Nov 2011" "Version 3.5.0" "NX Proxy" +.TH nxproxy 1 "June 2016" "Version 3.6.x" "NX Proxy" .SH NAME nxproxy \- NX Proxy Tool .SH SYNOPSIS 'nh .fi .ad l -\fBnxproxy\fR +\fBnxproxy\fR \fI[] :\fR .SH DESCRIPTION \fBnxproxy\fR is a tool that allows one to tunnel X sessions through -the NX compression libraries. \fBnxproxy\fR is a backend application -utilized by the X2GoClient GUI and some other NX/X2Go clients. -.PP -.SH OPTIONS -For an insight in \fBnxproxy\fR options use \fBnxproxy \-help\fR on the command line. +the NX compression library. \fBnxproxy\fR is a backend application +utilized by various client application (Remmina, X2Go Client, PyHoca-Gui, +Arctica Client, TheQVD Client, etc.). .PP +.SH COMMAND LINE OPTIONS +.TP 8 +.B -C +Specify that nxproxy has to run on the 'X client' side, listening for +connections and impersonating an X server. +.TP 8 +.B -S +Specify that nxproxy has to run in 'X server' mode, thus forwarding the +connections to daemons running on the client. +.TP 8 +.B -h +Print this message. +.TP 8 +.B -v +Print version information. +.TP 8 +.B : +Put at the end, specifies the host and port of the listening proxy. + +.SH NX/NX DISPLAY OPTIONS +Multiple nx/nx options can be specified in the DISPLAY environment or on +the command line, by using the nx/nx,option=value notation. +.TP 8 +.B link= +An indication of the link speed that is going to be used between the +proxies. Usually the compression and the other link parameters depend on +this setting. The value can be either 'modem', 'isdn', 'adsl', 'wan', +'lan', 'local' or a bandwidth specification, like for example '56k', +'1m', '100m', etc. + +.TP 8 +.B type= +Type of session, for example 'windows', 'unix-kde'. 'unix-application', +etc. + +.TP 8 +.B display= +Specify the real display where X connections have to be forwarded by the +proxy running on the client. + +.TP 8 +.B listen= +Local port used for accepting the proxy connection. + +.TP 8 +.B loopback= +Bind to the loopback device only. + +.TP 8 +.B accept= +Name or IP of host that can connect to the proxy. + +.TP 8 +.B connect= +Name or IP of host that the proxy will connect to. + +.TP 8 +.B port= +Remote port used for the connection. + +.TP 8 +.B retry= +Number of connection atempts. + +.TP 8 +.B root= +The root directory for the session. Usually is the C\-* or S\-* in the .nx +directory in the user's home, with '*' being the virtual display. + +.TP 8 +.B session= +Name of the session file. The default is the name 'session' in the +session directory. + +.TP 8 +.B errors= +Name of the log file used by the proxy. The default is the name 'errors' +in the session directory. + +.TP 8 +.B stats= +Name of the file where are written the proxy statistics. The default is a +file 'stats' in the session directory. The proxy replaces the data in the +file whenever it receives a SIGUSR1 or SIGUSR2 signal: + +.I SIGUSR1: +Gives total statistics, i.e. statistics collected since the beginning of +the session. + +.I SIGUSR2: +Gives partial statistics, i.e. statistics collected since the last time +this signal was received. + +.TP 8 +.B cookie= +Use the provided cookie for authenticating to the remote proxy. The same +cookie is used as the fake value used for the X authorization. The fake +cookie is replaced on the X server side with the real cookie to be used +for the display, so that the real cookie doesn't have to travel over the +net. When not using a proxy cookie, any host will be able to connect to +the proxy. See also the 'accept' parameter. + +.TP 8 +.B nodelay= +A boolean indicating if TCP_NODELAY has to be set on the proxy link. Old +Linux kernels had problems with handling TCP_NODELAY on PPP links. + +.TP 8 +.B policy= +Let or not the agent decide when it is the best time to flush the proxy +link. If set to 0, the proxy will flush any encoded data immediately. The +option has only effect on the X client side proxy. + +.TP 8 +.B render= +Enable or disable use of the RENDER extension. + +.TP 8 +.B taint= +Try to suppress trivial sources of X roundtrips by generating the reply +on the X client side. + +.TP 8 +.B delta= +Enable X differential compression. + +.TP 8 +.B data= +Enable or disable the ZLIB data compression. It is possible to specify a +value between 0 and 9. Usually the value is chosen automatically based on +the requested link setting. + +.TP 8 +.B stream= +Enable or disable the ZLIB stream compression. The value, between 0 and +9, is usually determined according to the requested link setting. Not +fully implemented in nx-X11 Agent, yet. + +.TP 8 +.B limit= +Specify a bitrate limit allowed for this session. + +.TP 8 +.B memory= +Trigger memory optimizations used to keep small the size of X buffers. +This is useful on embedded plat- forms, or where memory is scarce. + +.TP 8 +.B cache= +Size of the in-memory X message cache. Setting the value to 0 will +disable the memory cache as well as the NX differential compression. + +.TP 8 +.B images= +Size of the persistent image cache. + +.TP 8 +.B shseg= +Enable the use of the MIT-SHM extension between the \fBnxproxy\fR and the +real X server. A value greater than 1 is assumed to be the size of +requested shared memory segment. By default, the size of the segment is +determined based on the size of the in-memory cache. + +.TP 8 +.B load= +Enable loading a persistent X message cache at the proxy startup. + +.TP 8 +.B save= +Enable saving a persistent X message cache at the end of session. + +.TP 8 +.B cups= +Enable or disable forwarding of CUPS connections, by listening on the +optional port 'n'. + +.TP 8 +.B aux= +Enable or disable forwarding of the auxiliary X channel used for +controlling the keyboard. The 'keybd=' form is accepted for backward +compatibility. + +.TP 8 +.B smb= +Enable or disable forwarding of SMB connections. The 'samba=' form is +accepted for backward compatibility. + +.TP 8 +.B media= +Enable forwarding of audio connections. + +.TP 8 +.B http= +Enable forwarding of HTTP connections. + +.TP 8 +.B font= +Enable forwarding of reversed connections to a font +server running on the NX server. + +.TP 8 +.B file= +Enable forwarding of file transfer connections. + +.TP 8 +.B mask= +Determine the distribution of channel ids between the proxies. By +default, channels whose ids are multiple of 8 (starting from 0) are +reserved for the NX client side. All the other channels can be allocated +by the nx-X11 Agent side. + +.TP 8 +.B timeout=t +Specify the keep-alive timeout used by proxies to determine if there is a +network problem preventing communication with the remote peer. A value of +0 disables the check. + +.TP 8 +.B cleanup=t +Specify the number of seconds the proxy has to wait at session shutdown +before closing all channels. The feature is used by the NX server to +ensure that services are disconnected before shutting down the link. + +.TP 8 +.B pack= +Determine the method used to compress images. + +.TP 8 +.B product= +The product id of the client or server. The value is ignored by the +proxy, but the client or server can provide it to facilitate the support. + +.TP 8 +.B core= +Enable production of core dumps when aborting the proxy connection. + +.TP 8 +.B options= +Specify an additional file containing options that has to be merged with +option read from the command line or the environment. + +.TP 8 +.B kill= +Add the given process to the list of daemons that must be terminated at +session shutdown. Multiple 'kill=' options can be specified. The proxy +will send them a SIGTERM signal just before exiting. + +.TP 8 +.B strict= +Optimize for responsiveness, rather than for the best use of all the +available bandwidth. + +.TP 8 +.B encryption= +Should be set to 1 if the proxy is running as part of a program providing +encryption of the point to point communication. + +.TP 8 +.I These options are interpreted by the nx-NX Agent. They are ignored by the proxy. + + rootless= + geometry= + resize= + fullscreen= + keyboard= + clipboard= + streaming= + backingstore= + composite= + xinerama= + shmem= + shpix= + kbtype= + client= + shadow= + shadowuid= + shadowmode= + defer= + tile= + menu= + sleep= + +.SH NX ENVIRONMENT VARIABLES + +The \fBnxproxy\fR application (and also \fBnxagent\fR when using nxcomp +support) can be influenced by the following environment variables: + + +.TP 8 +.B NX_ROOT +The root NX directory is the place where the session directory and the +cache files are created. This is usually overridden by passing the +'root=' option. By default, the root NX directory is assumed to be the +directory '.nx' in the user's home. + +.TP 8 +.B NX_SYSTEM +The directory where NX programs and libraries reside. If not set, the +value is assumed to be '/usr/NX'. Programs, libraries and data files are +respectedly searched in the 'bin', 'lib' and 'share' subdirectories. + +.TP 8 +.B NX_HOME +The NX user's home directory. If NX_ROOT is not set or invalid, the +user's NX directory is created here. + +.TP 8 +.B NX_TEMP +The directory where the X11 Unix Domain Sockets and all temporary files +are to be created. + +.TP 8 +.B NX_CLIENT +The full path to the executable. If the variable is not set, +the executable will be run assuming that the program is in the +system path. This can be useful on platforms like Windows and the MacOS X +where is located in a different directory compared to the +other programs, to make easier for the user to execute the program from +the shell. + +.SH SHELL ENVIRONMENT VARIABLES + +.TP 8 +.B HOME +The variable is checked in the case NX_HOME is not set, null or invalid. + +.TP 8 +.B TEMP +The variable is checked whenever the NX_TEMP directory is not set, null +or invalid. + +.TP 8 +.B PATH +The path where all executables are searched, except . If +NX_CLIENT is not set, also the client executable is searched in the +system path. + +.TP 8 +.B LD_LIBRARY_PATH +System-wide library search order. This should be set by the program +invoking the proxy. + +.TP 8 +.B DISPLAY +On the X server side, the DISPLAY variable indicates the location of the +X11 server. When nxcomp is used as a transport library, the DISPLAY may +represent a NX transport specification and options can passed in the form +nx/nx,option=value... + +.TP 8 +.B XAUTHORITY +This is the file containing the X11 authorization cookie. If not set, the +file is assumed to be in the user's home (either NX_HOME or HOME). + .SH AUTHOR -This manual has been written by Mike Gabriel for the X2Go project -(http://www.x2go.org). +The \fBnxproxy\fR application has originally been derived from a sofware +project called DXCP. The company NoMachine turned DXCP into nxcomp with +nxproxy as executable around nxcomp. +.PP +The current maintenance of \fBnxproxy\fR (major version 3) is coordinated +between various projects, mainly by The Arctica Project, TheQVD (Qindel +Group) and the X2Go Project. +.PP +This manual has been written by Mike Gabriel + for the X2Go project +(http://www.x2go.org) and later on improved for the Arctica Project +(https://arctica-project.org). -- cgit v1.2.3