xrdp.ini(5)

📦
version 0.10.6.1 · 11 versions
, in epel 9, fedora 43, fedora 44, ubuntu stonking

💖 xrdp.ini 💖

okay bestie, welcome to xrdp.ini(5) — the manual page for the config file that runs the whole show for xrdp(8). this is part one of three, so grab a snack, we're going section by section 🍓

✨ NAME ✨

xrdp.ini — the configuration file for xrdp(8). that's it, that's the name, she's iconic, she's the blueprint 💅

🌸 DESCRIPTION 🌸

so here's the tea, bestie: this is the man page for xrdp.ini, which is the config file for xrdp(8). the way this file is built is genuinely so simple it's giving main character energy ✨

the file is made up of a bunch of sections. each section is composed of:

  1. a section name, wrapped up in square brackets — like [something] 🎀
  2. followed by a list of <parameter>=<value> lines

that's the whole structure. no cap. 🫶

🦋 sections you'll find in here

xrdp.ini supports the following sections:

  • [Globals] — sets some global configuration settings for xrdp(8). the big-picture vibes 🌈
  • [Logging] — logging subsystem parameters. everything the logs are keeping track of 💜
  • [Channels] — channel subsystem parameters. the channels doing their thing 🔥

💫 one little rule about case

every single option and value is case insensitive — EXCEPT for file names and paths. those are picky, they care about their letters, respect that 🙈

and all of them are described in detail below, so keep reading bestie, the good stuff is coming ✨

✨ GLOBALS ✨

okay so bestie, these are all the options that live in the [Globals] section of your xrdp.ini 💖

  • port=port_specification [ port_specification ... ] — tell xrdp which port(s) it should be listening on, fr. More instructions and examples are living right there inside xrdp.ini itself, go peek 👀
  • vmconnect=[true|false] — (Hyper-V VMs only, no cap). This one enables wider support of security protocols when a VM running xrdp is hosted on Hyper-V and the user connects to it through the vmms service on TCP port 2179. In this setup, RDP security is handled by the vmms service, so security features that haven't been added to xrdp yet can still be supported.

This parameter is required in environments that don't support 'classic' RDP encryption.

It gets ignored for connections that aren't made to the virtual machine over the vsock transport, just so you know.

  • autorun=session_name — the section name for automatic login. If it's set and the client hands over a valid username and password, the user gets logged in automatically using the connection specified by session_name. Iconic.

If session_name is empty, the LOGIN DOMAIN from the client is used to pick the section. And if no domain name is supplied at all, the first suitable section gets used for automatic login ✨

  • bitmap_cache=[true|false] — set it to 1, true or yes and this turns on bitmap caching in xrdp(8) 🎀
  • bitmap_compression=[true|false] — set it to 1, true or yes and bitmap compression in xrdp(8) is enabled 💅
  • bulk_compression=[true|false] — set it to 1, true or yes and compression of bulk data in xrdp(8) is enabled 🦋
  • certificate=/path/to/certificate
  • key_file=/path/to/private_key — these two set the location of the TLS certificate and private key. They must be written in PEM format. If you don't specify them, it defaults to /etc/xrdp/cert.pem and /etc/xrdp/key.pem.

Heads up: this parameter only does anything if security_layer is set to tls or negotiate.

  • tls_pms_log_file=<path-to-log-file> — logs TLS pre-master secrets to the file you point at. That lets packet capture tools (e.g. Wireshark) decrypt captured PDUs 👑

The file needs to be writeable by xrdp and readable by the packet capture tool. A good way to achieve this is to make 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. periodt.
  • channel_code=[true|false] — set it to 0, false or no and this disables all channels in xrdp(8). Want something more granular? See the CHANNELS section below, iykyk.
  • crypt_level=[low|medium|high|fips] — regulates the encryption level of Standard RDP Security. This parameter only does anything if security_layer is set to rdp or negotiate.

Encryption in Standard RDP Security is controlled by two settings: Encryption Level and Encryption Method. The only supported Encryption Methods are 40BIT_ENCRYPTION and 128BIT_ENCRYPTION. 56BIT_ENCRYPTION is not supported. This option controls the Encryption Level:

  • low — all data sent from the client to the server is protected by encryption based on the maximum key strength supported by the client. This is the only level where the traffic sent by the server to the client is not encrypted 👀
  • 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).
  • high — all data sent between the client and the server is protected by encryption based on the server's maximum key strength (server compatible).
  • fips — all data sent between the client and server is protected using Federal Information Processing Standard 140-1 validated encryption methods. This level is required for Windows clients (mstsc.exe) if the client's group policy enforces FIPS-compliance mode 🔥
  • fork=[true|false] — set it to 1, true or yes and xrdp(8) forks a sub-process for each incoming connection instead of using threads 🌈
  • hidelogwindow=[true|false] — set it to 1, true or yes and xrdp will not show a window for log messages. If you don't specify it, it defaults to false.
  • max_bpp=[8|15|16|24|32] — limit the color depth by giving the maximum number of bits per pixel. If you don't set it, or you set it to 0, it's unlimited 💜
  • pamerrortxt=error_text — extra text shown to the user if authentication fails. Maximum length is 256.

The use of 'pam' in the name of this option is historic, bestie, don't overthink it.

  • port=port — specify the TCP port and interface to listen on for incoming connections. If you only give the port, xrdp listens on all interfaces. The default port for RDP is 3389. Multiple address:port instances must be separated by spaces or commas — check the .ini file for examples. And specifying interfaces means those interfaces have to be UP before xrdp starts, no exceptions 🌸
  • runtime_user=username
  • runtime_group=groupname — the 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 it's running without system privilege. Very demure, very mindful.

The runtime_group MUST be set to the same value as SessionSockdirGroup in sesman.ini if you want to run sessions. Don't skip that part 🙈

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

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

And 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 the required files by running this script:

/usr/share/xrdp/xrdp-chkpriv
  • enable_token_login=[true|false] — if set to 1, true or yes, xrdp will scan the user name provided by the client for the ASCII field separator character (0x1F). Then it copies over whatever comes after the separator as the password supplied by the user, and treats it as autologon. If you don't specify it, it defaults to false ✨
  • domain_user_separator=separator — if specified, the domain name supplied by the client gets appended to the username, separated by separator.
  • require_credentials=[true|false] — if set to 1, true or yes, xrdp requires clients to include username and password in the initial connection phase. In other words, xrdp won't let clients show a login screen when this is true. Which means an incorrect password will make the login fail immediately, without ever displaying the login screen. If you don't specify it, it defaults to false 💀
  • security_layer=[tls|rdp|negotiate] — regulates security methods. If you don't specify it, it defaults to negotiate.
    • tls — Enhanced RDP Security is used. All security operations (encryption, decryption, data integrity verification, and server authentication) are implemented by TLS 👑
    • rdp — Standard RDP Security is used, which is not safe from man-in-the-middle attack. The encryption level of Standard RDP Security is controlled by crypt_level.
    • negotiate — negotiate these security methods with clients.
  • ssl_protocols=[SSLv3] [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3] — enables the specified SSL/TLS protocols. Each value should be separated by a comma. SSLv2 is always disabled. At least one protocol should be given to accept TLS connections. This parameter only does anything if security_layer is set to tls or negotiate 🎀
  • tcp_keepalive=[true|false] — regulates whether the listening socket uses the socket option SO_KEEPALIVE. If set to 1, true or yes and the network connection disappears without closing messages, the connection will be closed.
  • tcp_nodelay=[true|false] — regulates whether the listening socket uses the socket option TCP_NODELAY. If set to 1, true or yes, no buffering will be performed in the TCP stack ⚡
  • tcp_send_buffer_bytes=buffer_size
  • tcp_recv_buffer_bytes=buffer_size — specify send/recv buffer sizes in bytes. The default value depends on the operating system. It's recommended not to set these on systems with dynamic TCP buffer sizing.
  • tls_ciphers=cipher_suite — specifies the TLS cipher suite. The format of this parameter is equivalent to what the openssl(1) ciphers subcommand accepts.

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

This parameter only does anything if security_layer is set to tls or negotiate 💅

  • use_fastpath=[input|output|both|none] — if you don't specify it, it defaults to none.
  • black=000000
  • grey=c0c0c0
  • dark_grey=808080
  • blue=0000ff
  • dark_blue=00007f
  • white=ffffff
  • red=ff0000
  • green=00ff00
  • background=000000 — these options override the colors xrdp(8) uses internally to draw the login and log windows. Colors are defined using hexadecimal (hex) notation for the combination of Red, Green, and Blue color values (RGB). The lowest value you can give one of the light sources is 0 (hex 00). The highest value is 255 (hex FF) 🌈
  • fv1_select=130:sans-18.fv1,0:sans-10.fv1 — 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 🦋
  • default_dpi=96 — the default DPI used for a monitor if the client doesn't send physical size information.

💻 LOGGING 💻

okay bestie so the [Logging] section is where you tell xrdp how loud it should be and where it should scream into. here's the lineup:

  • LogFile=/var/log/xrdp.log — this one holds the path to the logfile. it can be absolute or relative, whatever your heart desires. and if you set it to <stdout>, the log goes to stdout instead. only use that for debugging tho, fr fr
  • LogLevel=level — set the vibe of your logging. the options are:
    • CORE or 0 — only core messages get logged. these ones are _always_ logged, no matter what logging level you picked. they're the main characters, they don't take days off 💅
    • ERROR or 1 — only error messages. pure drama, nothing else.
    • WARNING, WARN or 2 — warnings and errors both show up.
    • INFO or 3 — errors, warnings and informational messages. the balanced girlie.
    • DEBUG or 4 — logs literally everything. and if xrdp-sesman was compiled in debug mode, this option outputs so many more low-level messages, which is super useful for developers 🛠️
  • EnableSyslog=[true|false] — set this to 1, true or yes and syslog logging is on. otherwise syslog is disabled, periodt.
  • SyslogLevel=level — this sets the logging level for syslog specifically. it takes the same values as LogLevel. heads up tho: if SyslogLevel is greater than LogLevel, its value gets lowered down to whatever LogLevel is. no overachieving here 🙈
  • EnableConsole=[true|false] — set to 1, true or yes and this enables logging to the console (aka stdout).
  • ConsoleLevel=level — the logging level for the console. takes the same values as LogLevel. defaults to DEBUG.
  • EnableProcessId=[true|false] — set to 1, true or yes and every log message gets the process id in it. defaults to false.

📡 CHANNELS 📡

so RDP supports a bunch of channels, right? they're how extra data like sound, clipboard stuff and other goodies get transferred. channel names that aren't listed here get blocked by xrdp, so don't be surprised.

also important: not every channel is supported in every situation, so setting a value to true is a prerequisite — but it does not force the channel to actually be used. it's giving "you're allowed, not obligated" energy.

oh and you can enable or disable channels on a per-connection basis too, by prefixing each setting with channel. in the channel section. cute, right? 🎀

  • rdpdr=[true|false] — set to 1, true or yes and using the RDP channel for device redirection is allowed.
  • rdpsnd=[true|false] — set to 1, true or yes and using the RDP channel for sound is allowed.
  • drdynvc=[true|false] — set to 1, true or yes and using the RDP channel to initiate additional dynamic virtual channels is allowed.
  • cliprdr=[true|false] — set to 1, true or yes and using the RDP channel for clipboard redirection is allowed.
  • rail=[true|false] — set to 1, true or yes and using the RDP channel for remote applications integrated locally (RAIL) is allowed.
  • xrdpvr=[true|false] — set to 1, true or yes and using the RDP channel for XRDP Video streaming is allowed.

🔌 CONNECTIONS 🔌

a connection section is made of a section name wrapped in square brackets, plus these entries:

  • name=<session name> — the name that shows up in the xrdp(8) login window's combo box. it's the little label bestie ✨
  • lib=../vnc/libvnc.so — sets the library to be used with this connection.
  • username=<username>|{base64}<base64-encoded-username>|ask — specifies the username used for authenticating in the connection. if you set it to ask, the user name should be provided in the login window.

if the username includes comment-out symbols like '#' or ';', you can provide the username in base64 form by prefixing it with "{base64}".

  • password=<password>|{base64}<base64-encoded-password>|ask — specifies the password used for authenticating in the connection. if set to ask, the password should be provided in the login window.

this parameter can be provided in base64 form too, just like username. see the examples below 👇

  • ip=127.0.0.1 — specifies the ip address of the host to connect to.
  • port=<number>|-1 — specifies the port number to connect to. if you set it to -1, the default port for the specified library gets used.
  • xserverbpp=<number> — specifies the color depth of the backend X server. the default is the color depth of the client. only Xvnc uses this setting btw — Xorg runs at 24 bpp.
  • disabled_encodings_mask=<number> — set this bitmask to a non-zero value to stop xrdp(8) from 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 xrdp(8) are documented in xrdp.ini.
  • code=<number>|0 — specifies the session type. 0 is Xvnc over TCP, 1 is Xvnc over a UNIX domain socket, and 20 is Xorg with xorgxrdp modules. the default is 0 on non-FIPS systems, and 1 on FIPS systems.
  • chansrvport=DISPLAY(n)|DISPLAY(n,u)||/path/to/domain-socket — asks xrdp to connect to a manually started xrdp-chansrv instance. this is useful if you wanna use xrdp to connect to a VNC session that was started by something other than xrdp-sesman, because then you get to make use of xrdp-chansrv facilities inside that VNC session. iconic 🫶

either the first or the second form of this setting is recommended. replace n with the X11 display number of the session, and (if it applies) u with the numeric ID of the session. the second form is only needed if xrdp can't figure out the session uid from the other values in the connection block.

  • h264_frame_interval=<integer> — [Xorg only] specify frame capture interval for H.264 captures in milliseconds.
  • rfx_frame_interval=<integer> — [Xorg only] specify frame capture interval for RemoteFX captures in milliseconds.
  • normal_frame_interval=<integer> — [Xorg only] specify frame capture interval for normal captures in milliseconds.

🌈 EXAMPLES 🌈

here's an example xrdp.ini, bestie — copy the vibe, not the paste:

[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==

📁 FILES 📁

  • /etc/xrdp/xrdp.ini

👀 SEE ALSO 👀

xrdp(8), xrdp-chansrv(8), xrdp-sesman(8), xrdp-sesrun(8), sesman.ini(5)

for more info on xrdp see http://www.xrdp.org/

and that's the whole page, babe 💖 this was written by the xrdp team, it's version 0.10.6.1, and it's dated xrdp.ini(5). go forth and configure, you absolute legend 👑

📦 where this page comes from