.TH "xrdp.ini" "5" "@PACKAGE_VERSION@" "xrdp team" ""
.SH "NAME"
\fBxrdp.ini\fR \- Configuration file for \fBxrdp\fR(8)

.SH "DESCRIPTION"
This is the man page for \fBxrdp.ini\fR, \fBxrdp\fR(8) configuration file.
It is composed by a number of sections, each one composed by a section name, enclosed by square brackets, followed by a list of \fI<parameter>\fR=\fI<value>\fR lines.

\fBxrdp.ini\fR supports the following sections:

.TP
\fB[Globals]\fP \- sets some global configuration settings for \fBxrdp\fR(8).

.TP
\fB[Logging]\fP \- logging subsystem parameters

.TP
\fB[Channels]\fP \- channel subsystem parameters

.LP
All options and values (except for file names and paths) are case insensitive, and are described in detail below.

.SH "GLOBALS"
The options to be specified in the \fB[Globals]\fR section are the following:

.TP
\fBport\fR=\fIport_specification [ port_specification ... ]\fR
Specify the port(s) that xrdp should listen on. More instructions and
examples can be found within xrdp.ini itself.

.TP
\fBvmconnect\fR=\fI[true|false]\fR
(Hyper-V VMs only). Enables a wider support of security protocols when a
virtual machine running xrdp is hosted on Hyper-V, and the user connects
to it via the vmms service on TCP port 2179. In this configuration,
RDP security is handled by the vmms service, and security features which
are not yet added to xrdp itself can be supported.

This parameter is required in environments which do not support 'classic'
RDP encryption.

The parameter is ignored for connections which are not made to the
virtual machine over the vsock transport.

.TP
\fBautorun\fP=\fIsession_name\fP
Section name for automatic login. If set and the client supplies valid
username and password, the user will be logged in automatically using the
connection specified by \fIsession_name\fP.

If \fIsession_name\fP is empty, the \fBLOGIN DOMAIN\fR from the client
with be used to select the section. If no domain name is supplied, the
first suitable section will be used for automatic login.

.TP
\fBbitmap_cache\fR=\fI[true|false]\fR
If set to \fB1\fR, \fBtrue\fR or \fByes\fR this option enables bitmap caching in \fBxrdp\fR(8).

.TP
\fBbitmap_compression\fR=\fI[true|false]\fR
If set to \fB1\fR, \fBtrue\fR or \fByes\fR this option enables bitmap compression in \fBxrdp\fR(8).

.TP
\fBbulk_compression\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR this option enables compression of bulk data in \fBxrdp\fR(8).

.TP
\fBcertificate\fP=\fI/path/to/certificate\fP
.TP
\fBkey_file\fP=\fI/path/to/private_key\fP
Set location of TLS certificate and private key. They must be written in PEM format.
If not specified, defaults to \fB@sysconfdir@/@sysconfsubdir@/cert.pem\fP, \fB@sysconfdir@/@sysconfsubdir@/key.pem\fP.

This parameter is effective only if \fBsecurity_layer\fP is set to \fBtls\fP or \fBnegotiate\fP.

.TP
\fBtls_pms_log_file\fR=\fI<path-to-log-file>\fR
Logs TLS pre-master secrets to the specified file. This allows packet capture
tools (e.g. Wireshark) to decrypt captured PDUs.

The file must be writeable by xrdp and readable by the packet capture tool.
A good way to achive this is to create a temporary directory with
permissions 2750 owned by the user running xrdp, and in the group used by
the packet sniffer.

SETTING THIS OPTION IS A SECURITY RISK. ONLY SET THIS OPTION FOR DEBUGGING
COMMUNICATIONS BETWEEN XRDP AND A CLIENT.

.TP
\fBchannel_code\fP=\fI[true|false]\fP
If set to \fB0\fR, \fBfalse\fR or \fBno\fR this option disables all channels \fBxrdp\fR(8).
See section \fBCHANNELS\fP below for more fine grained options.

.TP
\fBcrypt_level\fP=\fI[low|medium|high|fips]\fP
.\" <http://blogs.msdn.com/b/openspecification/archive/2011/12/08/encryption-negotiation-in-rdp-connection.aspx>
Regulate encryption level of Standard RDP Security.
This parameter is effective only if \fBsecurity_layer\fP is set to \fBrdp\fP or \fBnegotiate\fP.

Encryption in Standard RDP Security is controlled by two settings: \fIEncryption Level\fP
and \fIEncryption Method\fP.  The only supported \fIEncryption Method\fP are \fB40BIT_ENCRYPTION\fP
and \fB128BIT_ENCRYPTION\fP. \fB56BIT_ENCRYPTION\fP is not supported.
This option controls the \fIEncryption Level\fP:
.RS 8
.TP
.B low
All data sent from the client to the server is protected by encryption based on
the maximum key strength supported by the client.
.I This is the only level that the traffic sent by the server to client is not encrypted.
.TP
.B medium
All data sent between the client and the server is protected by encryption based on
the maximum key strength supported by the client (client compatible).
.TP
.B high
All data sent between the client and the server is protected by encryption based on
the server's maximum key strength (sever compatible).
.TP
.B fips
All data sent between the client and server is protected using Federal Information
Processing Standard 140-1 validated encryption methods.
.I This level is required for Windows clients (mstsc.exe) if the client's group policy
.I enforces FIPS-compliance mode.
.RE

.TP
\fBfork\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR for each incoming connection \fBxrdp\fR(8) forks a sub-process instead of using threads.

.TP
\fBhidelogwindow\fP=\fI[true|false]\fP
If set to \fB1\fP, \fBtrue\fP or \fByes\fP, \fBxrdp\fP will not show a window for log messages.
If not specified, defaults to \fBfalse\fP.

.TP
\fBmax_bpp\fP=\fI[8|15|16|24|32]\fP
Limit the color depth by specifying the maximum number of bits per pixel.
If not specified or set to \fB0\fP, unlimited.

.TP
\fBpamerrortxt\fP=\fIerror_text\fP
Specify additional text displayed to user if authentication fails. The maximum length is \fB256\fP.

The use of 'pam' in the name of this option is historic

.TP
\fBport\fP=\fIport\fP
Specify TCP port and interface to listen on for incoming connections.
Specifying only the port means that xrdp will listen on all interfaces.
The default port for RDP is \fB3389\fP.
Multiple address:port instances must be separated by spaces or commas. Check the .ini file for examples.
Specifying interfaces requires said interfaces to be UP before xrdp starts.

.TP
\fBruntime_user\fP=\fIusername\fP
.TP
\fBruntime_group\fP=\fIgroupname\fP
User name and group to run the xrdp daemon under.

After xrdp starts, it sets its UID and GID to values derived from these
settings, so that it's running without system privilege.

The \fBruntime_group\fP MUST be set to the same value as
\fBSessionSockdirGroup\fP in \fBsesman.ini\fP if you want to run sessions.

A suitable user and group can be added with a command like this (Linux):-

useradd xrdp -d / -c 'xrdp daemon' -s /usr/sbin/nologin

In order to establish secure connections, the xrdp daemon needs permission
to access sensitive cryptographic files. After changing either or both
of these values, check that xrdp has access to required files by running
this script:-

@xrdpdatadir@/xrdp-chkpriv

.TP
\fBenable_token_login\fP=\fI[true|false]\fP
If set to \fB1\fP, \fBtrue\fP or \fByes\fP, \fBxrdp\fP will scan the user name provided by the
client for the ASCII field separator character (0x1F). It will then copy over what is after the
separator as the password supplied by the user and treats it as autologon. If not specified,
defaults to \fBfalse\fP.

.TP
\fBdomain_user_separator\fP=\fBseparator\fP
If specified the domain name supplied by the client is appended to the username separated
by \fBseparator\fP.

.TP
\fBrequire_credentials\fP=\fI[true|false]\fP
If set to \fB1\fP, \fBtrue\fP or \fByes\fP, \fBxrdp\fP requires clients
to include username and password initial connection phase. In other
words, xrdp doesn't allow clients to show login screen if set to true.
It follows that an incorrect password will cause the login to immediately
fail without displaying the login screen.  If not specified, defaults
to \fBfalse\fP.

.TP
\fBsecurity_layer\fP=\fI[tls|rdp|negotiate]\fP
Regulate security methods. If not specified, defaults to \fBnegotiate\fP.
.RS 8
.TP
.B tls
Enhanced RDP Security is used. All security operations (encryption, decryption, data integrity
verification, and server authentication) are implemented by TLS.

.TP
.B rdp
Standard RDP Security, which is not safe from man-in-the-middle attack, is used. The encryption level
of Standard RDP Security is controlled by \fBcrypt_level\fP.

.TP
.B negotiate
Negotiate these security methods with clients.
.RE

.TP
\fBssl_protocols\fP=\fI[SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]\fP
Enables the specified SSL/TLS protocols. Each value should be separated by comma.
SSLv2 is always disabled. At least one protocol should be given to accept TLS connections.
This parameter is effective only if \fBsecurity_layer\fP is set to \fBtls\fP or \fBnegotiate\fP.

.TP
\fBtcp_keepalive\fP=\fI[true|false]\fP
Regulate if the listening socket uses socket option \fBSO_KEEPALIVE\fP.
If set to \fB1\fP, \fBtrue\fP or \fByes\fP and the network connection disappears
without closing messages, the connection will be closed.

.TP
\fBtcp_nodelay\fP=\fI[true|false]\fP
Regulate if the listening socket uses socket option \fBTCP_NODELAY\fP.
If set to \fB1\fP, \fBtrue\fP or \fByes\fP, no buffering will be performed in the TCP stack.

.TP
\fBtcp_send_buffer_bytes\fP=\fIbuffer_size\fP
.TP
\fBtcp_recv_buffer_bytes\fP=\fIbuffer_size\fP
Specify send/recv buffer sizes in bytes.  The default value depends on
the operating system. It is recommended not to set these on systems with
dynamic TCP buffer sizing

.TP
\fBtls_ciphers\fP=\fIcipher_suite\fP
Specifies TLS cipher suite. The format of this parameter is equivalent
to which \fBopenssl\fP(1) ciphers subcommand accepts.

(ex. $ openssl ciphers 'HIGH:!ADH:!SHA1')

This parameter is effective only if \fBsecurity_layer\fP is set to \fBtls\fP or \fBnegotiate\fP.

.TP
\fBuse_fastpath\fP=\fI[input|output|both|none]\fP
If not specified, defaults to \fBnone\fP.

.TP
\fBblack\fP=\fI000000\fP
.TP
\fBgrey\fP=\fIc0c0c0\fP
.TP
\fBdark_grey\fP=\fI808080\fP
.TP
\fBblue\fP=\fI0000ff\fP
.TP
\fBdark_blue\fP=\fI00007f\fP
.TP
\fBwhite\fP=\fIffffff\fP
.TP
\fBred\fP=\fIff0000\fP
.TP
\fBgreen\fP=\fI00ff00\fP
.TP
\fBbackground\fP=\fI000000\fP
These options override the colors used internally by \fBxrdp\fP(8) to draw the login and log windows.
Colors are defined using a hexadecimal (hex) notation for the combination of Red, Green, and Blue color values (RGB).
The lowest value that can be given to one of the light sources is 0 (hex 00).
The highest value is 255 (hex FF).
.TP
\fBfv1_select\fP=\fI130:sans-18.fv1,0:sans-10.fv1\fP
Selects a default fv1 font.
This parameter is a comma-separated list of DPI:name pairs.  The list
is scanned from left-to-right. The font used is the first font whose DPI
value is less-than-or-equal to the vertical DPI of the monitor used for
the login screen.
.TP
\fBdefault_dpi\fP=\fI96\fP
Default DPI used for a monitor if the client does not send physical
size information.


.SH "LOGGING"
The following parameters can be used in the \fB[Logging]\fR section:

.TP
\fBLogFile\fR=\fI@localstatedir@/log/xrdp.log\fR
This options contains the path to logfile. It can be either absolute or relative. If set to \fB<stdout>\fR, log will go to stdout. Use for debugging only\fR

.TP
\fBLogLevel\fR=\fIlevel\fR
This option can have one of the following values:

\fBCORE\fR or \fB0\fR \- Log only core messages. these messages are _always_ logged, regardless the logging level selected.

\fBERROR\fR or \fB1\fR \- Log only error messages

\fBWARNING\fR, \fBWARN\fR or \fB2\fR \- Logs warnings and error messages

\fBINFO\fR or \fB3\fR \- Logs errors, warnings and informational messages

\fBDEBUG\fR or \fB4\fR \- Log everything. If \fBxrdp-sesman\fR is compiled in debug mode, this options will output many more low\-level message, useful for developers

.TP
\fBEnableSyslog\fR=\fI[true|false]\fR
If set to \fB1\fR, \fBtrue\fR or \fByes\fR this option enables logging to syslog. Otherwise syslog is disabled.

.TP
\fBSyslogLevel\fR=\fIlevel\fR
This option sets the logging level for syslog. It can have the same values of \fBLogLevel\fR. If \fBSyslogLevel\fR is greater than \fBLogLevel\fR, its value is lowered to that of \fBLogLevel\fR.

.TP
\fBEnableConsole\fR=\fI[true|false]\fR
If set to \fB1\fR, \fBtrue\fR or \fByes\fR, this option enables logging to the console (ie. stdout).

.TP
\fBConsoleLevel\fR=\fIlevel\fR
Logging level for the console. It can have the same values as \fBLogLevel\fR. Defaults to \fBDEBUG\fR.

.TP
\fBEnableProcessId\fR=\fI[true|false]\fR
If set to \fB1\fR, \fBtrue\fR or \fByes\fR, this option enables logging the process id in all log messages. Defaults to \fBfalse\fR.

.SH "CHANNELS"
The Remote Desktop Protocol supports several channels, which are used to transfer additional data like sound, clipboard data and others.
Channel names not listed here will be blocked by \fBxrdp\fP.
Not all channels are supported in all cases, so setting a value to \fItrue\fP is a prerequisite, but does not force its use.
.br
Channels can also be enabled or disabled on a per connection basis by prefixing each setting with \fBchannel.\fP in the channel section.

.TP
\fBrdpdr\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel for device redirection is allowed.

.TP
\fBrdpsnd\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel for sound is allowed.

.TP
\fBdrdynvc\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel to initiate additional dynamic virtual channels is allowed.

.TP
\fBcliprdr\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel for clipboard redirection is allowed.

.TP
\fBrail\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel for remote applications integrated locally (RAIL) is allowed.

.TP
\fBxrdpvr\fP=\fI[true|false]\fP
If set to \fB1\fR, \fBtrue\fR or \fByes\fR using the RDP channel for XRDP Video streaming is allowed.

.SH "CONNECTIONS"
A connection section is made of a section name, enclosed in square brackets, and the following entries:

.TP
\fBname\fR=\fI<session name>\fR
The name displayed in \fBxrdp\fR(8) login window's combo box.

.TP
\fBlib\fR=\fI../vnc/libvnc.so\fR
Sets the library to be used with this connection.

.TP
\fBusername\fR=\fI<username>\fR|\fI{base64}<base64-encoded-username>\fR|\fIask\fR
Specifies the username used for authenticating in the connection.
If set to \fIask\fR, user name should be provided in the login window.

If the username includes comment out symbols such as '#', or ';', the username can be
provided in base64 form prefixing "{base64}".

.TP
\fBpassword\fR=\fI<password>\fR|\fI{base64}<base64-encoded-password>\fR|\fIask\fR
Specifies the password used for authenticating in the connection.
If set to \fIask\fR, password should be provided in the login window.

This parameter can be provided in base64 form as well as username. See also examples below.

.TP
\fBip\fR=\fI127.0.0.1\fR
Specifies the ip address of the host to connect to.

.TP
\fBport\fR=\fI<number>\fR|\fI\-1\fR
Specifies the port number to connect to. If set to \fI\-1\fR, the default port for the specified library is used.

.TP
\fBxserverbpp\fR=\fI<number>\fR
Specifies color depth of the backend X server. The default is the color
depth of the client. Only Xvnc uses that setting. Xorg runs at
\fI24\fR bpp.

.TP
\fBdisabled_encodings_mask\fR=\fI<number>\fR
Set this bitmask to a non-zero value to prevent \fBxrdp\fR(8) requesting
some features from the Xvnc server. You should only need to set this
to  a non-zero value to work around bugs in your Xvnc server. The bit
values supported for a particular release of \fBxrdp\fR(8) are documented in
\fBxrdp.ini\fR.

.TP
\fBcode\fR=\fI<number>\fR|\fI0\fR
Specifies the session type. \fI0\fR is Xvnc over TCP,
\fI1\fR is Xvnc over a UNIX domain socket,
and \fI20\fR is Xorg with xorgxrdp modules.
The default is \fI0\fR on non-FIPS systems, and \fI1\fR on FIPS systems.
.TP
\fBchansrvport\fR=\fBDISPLAY(\fR\fIn\fR\fB)\fR|\fBDISPLAY(\fR\fIn,u\fR\fB)\fR||\fI/path/to/domain-socket\fR
Asks xrdp to connect to a manually started \fBxrdp-chansrv\fR instance.
This can be useful if you wish to use to use xrdp to connect to a VNC session
which has been started other than by \fBxrdp-sesman\fR, as you can then make
use of \fBxrdp\-chansrv\fR facilities in the VNC session.

Either the first or second form of this setting is recommended. Replace
\fIn\fR with the X11 display number of the session, and (if applicable)
\fIu\fR with the numeric ID of the session. The second form is only
required if \fBxrdp\fR is unable to determine the session uid from the
other values in the connection block.

.TP
\fBh264_frame_interval\fR=\fI<integer>\fR
[Xorg only] Specify frame capture interval for H.264 captures in milliseconds.

.TP
\fBrfx_frame_interval\fR=\fI<integer>\fR
[Xorg only] Specify frame capture interval for RemoteFX captures in milliseconds.

.TP
\fBnormal_frame_interval\fR=\fI<integer>\fR
[Xorg only] Specify frame capture interval for normal captures in milliseconds.

.SH "EXAMPLES"
This is an example \fBxrdp.ini\fR:

.nf
[Globals]
bitmap_cache=true
bitmap_compression=true

[Xorg]
name=Xorg
lib=libxup.so
username=ask
password=ask
ip=127.0.0.1
port=-1
code=20
h264_frame_interval=16
rfx_frame_interval=32
normal_frame_interval=40

[vnc-any]
name=vnc-any
lib=libvnc.so
ip=ask
port=ask5900
username=na
password={base64}cGFzc3dvcmQhCg==
.fi

.SH "FILES"
@sysconfdir@/@sysconfsubdir@/xrdp.ini

.SH "SEE ALSO"
.BR xrdp (8),
.BR xrdp\-chansrv (8),
.BR xrdp\-sesman (8),
.BR xrdp\-sesrun (8),
.BR sesman.ini (5)

For more info on \fBxrdp\fR see
.UR @xrdphomeurl@
.UE