xfreerdp3(1)

📦

version 3.32.1 · 6 versions

okay bestie 💖 you opened the manual for xfreerdp3, and ngl she's a lot. This is the FreeRDP X11 client, and this page is LONG, so we're doing it in parts — this is part 1, and we are not skipping a single flag. periodt.

✨ NAME ✨

xfreerdp3 — FreeRDP X11 client. That's the whole thing. Short, sweet, iconic.

🌈 SYNOPSIS 🌈

xfreerdp3 [file] [options] [/v:server[:port]]

🦋 DESCRIPTION 🦋

So xfreerdp3 is an X11 Remote Desktop Protocol (RDP) client, and she's part of the FreeRDP project. Fun fact bestie: an RDP server is built-in to many editions of Windows. And if you're not on Windows? Don't even stress — alternative servers include ogon, gnome-remote-desktop, xrdp and VRDP (VirtualBox). You've got options, queen.

💅 OPTIONS 💅

okay this is the big one. one bullet per option, nothing skipped, no cap.

/a:addin[,options], /addin:addin[,options] — Addin
/azure:[tenantid:id],[use-tenantid[:[on|off]],[ad:url][avd-access:format string],[avd-token:format string],[avd-scope:format string],[auth-helper:path|autodetect] — AzureAD options
/action-script:file-name — Action script (default: ~/.config/freerdp/action.sh)
/admin, /console — Admin (or console) session
+aero — desktop composition (default: off)
/app:program:[path|||alias],cmd:command,file:filename,guid:guid,icon:filename,name:name,workdir:directory,hidef:[on|off] — Remote application program
/assistance:password — Remote assistance password
/auto-request-control: — Automatically request remote assistance input control
+async-channels — Asynchronous channels (experimental) (default: off)
+async-update — Asynchronous update (default: off)
/audio-mode:[[none|2]|[server|1]|[redirect|0]] — Audio output mode
+auth-only — Authenticate only (default: off)
/auth-pkg-list:[[none],]!ntlm,kerberos,!u2u — Authentication package filter (comma-separated list, use ! to disable). By default all methods are enabled. Use explicit none as first argument to disable all methods, selectively enabling only the ones following.
-authentication — Authentication (experimental) (default: on)
+auto-reconnect — Automatic reconnection (default: off)
/auto-reconnect-max-retries:retries — Automatic reconnection maximum retries, 0 for unlimited [0,1000]
/bpp:depth — Session bpp (color depth) (default: 16)
/buildconfig — Print the build configuration
/cache:[bitmap[:on|off],codec[:rfx|nsc],glyph[:on|off],offscreen[:on|off],persist,persist-file:filename] — Cache stuff
/cert:[deny,ignore,name:name,tofu,fingerprint:hash:hash as hex[,fingerprint:hash:another hash]] — Certificate accept options. Use with care!
- deny ... Automatically abort connection if the certificate does not match, no user interaction.
- ignore ... Ignore the certificate checks altogether (overrules all other options)
- name ... Use the alternate <name> instead of the certificate subject to match locally stored certificates
- tofu ... Accept certificate unconditionally on first connect and deny on subsequent connections if the certificate does not match
- fingerprints ... A list of certificate hashes that are accepted unconditionally for a connection
/client-build-number:number — Client Build Number sent to server (influences smartcard behaviour, see [MS-RDPESC])
/client-hostname:name — Client Hostname to send to server
/clipboard:[[use-selection:atom],[direction-to:[all|local|remote|off]],[files-to[:all|local|remote|off]]] — Redirect clipboard:
- use-selection:<atom> ... (X11) Specify which X selection to access. Default is CLIPBOARD. PRIMARY is the X-style middle-click selection.
- direction-to:[all|local|remote|off] control enabled clipboard direction
- files-to:[all|local|remote|off] control enabled file clipboard direction (default: on)
-compression, -z — compression (default: on)
/compression-level:level — Compression level (0,1,2)
+credentials-delegation — credentials delegation (default: off)
/d:domain — Domain
-decorations — Window decorations (default: on)
/disp — Display control
/drive:name,path — Redirect directory <path> as named share <name>. Hotplug support is enabled with /drive:hotplug,*. This argument provides the same function as "Drives that I plug in later" option in MSTSC.
+drives — Redirect all mount points as shares (default: off)
/dump:record|replay,file:file[,nodelay] — record or replay dump
/dvc:channel[,options] — Dynamic virtual channel
+dynamic-resolution — Send resolution updates when the window is resized (default: off)
/echo, /echo — Echo channel (yes, it's listed twice, and honestly? iconic.)
-encryption — Encryption (experimental) (default: on)
/encryption-methods:[40,][56,][128,][FIPS] — RDP standard security encryption methods
/endpointfedauth:token — Endpoint FedAuth token for Hyper-V VM console-connect scenarios
/f — Fullscreen mode (<Ctrl>+<Alt>+<Enter> toggles fullscreen)
+fipsmode — FIPS mode (default: off)
/floatbar[:sticky:[on|off],default:[visible|hidden],show:[always|fullscreen|window]] — floatbar is disabled by default (when enabled defaults to sticky in fullscreen mode)
-fonts — smooth fonts (ClearType) (default: on)
+force-console-callbacks — Use default callbacks (console) for certificate/credential/... (default: off)
/frame-ack:number — Number of frame acknowledgement
/args-from:file:file|stdin|fd:number|env:name — Read command line from a file, stdin or file descriptor. This argument can not be combined with any other. Provide one argument per line.
/from-stdin[:force] — Read credentials from stdin. With <force> the prompt is done before connection, otherwise on server request.
/gateway:g:gateway[:port],u:user,d:domain,p:password,usage-method:[direct|detect],access-token:token,type:[rpc|http[,no-websockets][,extauth-sspi-ntlm]|auto[,no-websockets][,extauth-sspi-ntlm]]|arm,url:wss://url,bearer:oauth2-bearer-token,timeout:1-600000 ms, /gw:g:gateway[:port],u:user,d:domain,p:password,usage-method:[direct|detect],access-token:token,type:[rpc|http[,no-websockets][,extauth-sspi-ntlm]|auto[,no-websockets][,extauth-sspi-ntlm]]|arm,url:wss://url,bearer:oauth2-bearer-token,timeout:1-600000 ms — Gateway Hostname
/gdi:sw|hw — GDI rendering
/geometry — Geometry tracking channel
+gestures — Consume multitouch input locally (default: off)
/gfx[:[progressive[:on|off]|RFX[:on|off]|AVC420[:on|off]AVC444[:on|off]],mask:value,small-cache[:on|off],thin-client[:on|off],progressive[:on|off]]] — RDP8 graphics pipeline
-grab-keyboard — Grab keyboard focus, forward all keys to remote (default: on)
-grab-mouse — Grab mouse focus, forward all events to remote (default: on)
/h:height — Height (default: 768)
-heartbeat — Support heartbeat PDUs (default: on)
/help, /? — Print help
+home-drive — Redirect user home as share (default: off)
/ipv4[:[:force]], /4[:[:force]] — Prefer IPv4 A record over IPv6 AAAA record
/ipv6[:[:force]], /6[:[:force]] — Prefer IPv6 AAAA record over IPv4 A record
/jpeg — JPEG codec support
/jpeg-quality:percentage — JPEG quality
/kbd:[layout:[0xid|name],lang:0xid,fn-key:value,type:value,subtype:value,unicode[:on|off],remap:key1=value1,remap:key2=value2,pipe:filename] — Keyboard related options:
- layout: set the keyboard layout announced to the server
- lang: set the keyboard language identifier sent to the server
- fn-key: Function key value
- remap: RDP scancode to another one. Use /list:kbd-scancode to get the mapping. Example: To switch a and s on a US keyboard: /kbd:remap:0x1e=0x1f,remap:0x1f=0x1e
- pipe: Name of a named pipe that can be used to type text into the RDP session
/kerberos:[kdc-url:url,lifetime:time,start-time:time,renewable-lifetime:time,cache:path,armor:path,pkinit-anchors:path,pkcs11-module:name] — Kerberos options
/load-balance-info:info-string — Load balance info
/list:[kbd|kbd-scancode|kbd-lang[:value]|smartcard[:[pkinit-anchors:path][,pkcs11-module:name]]|monitor|tune|timezones] — List available options for subcommand (default: List available options for subcommand)
/log-filters:tag:level[,tag:level[,...]] — Set logger filters, see wLog(7) for details
/log-level:[OFF|FATAL|ERROR|WARN|INFO|DEBUG|TRACE] — Set the default log level, see wLog(7) for details
/max-fast-path-size:size — Specify maximum fast-path update size
/max-loop-time:time — Specify maximum time in milliseconds spend treating packets
+menu-anims — menu animations (default: off)
/microphone[:[sys:sys,][dev:dev,][format:format,][rate:rate,][channel:channel]], /mic[:[sys:sys,][dev:dev,][format:format,][rate:rate,][channel:channel]] — Audio input (microphone)
/monitors:id[,id[,...]] — [experimental] Select monitors to use (only effective in fullscreen or multimonitor mode)
-mouse-motion — Send mouse motion events (default: on)
+mouse-relative — Send mouse motion with relative addressing (default: off)
/mouse:[relative:[on|off],grab:[on|off]] — Mouse related options:
- relative: send relative mouse movements if supported by server
- grab: grab the mouse if within the window
/multimon:on|off|force — Use multiple monitors (default: off)
+multitouch — Redirect multitouch input (default: off)
-multitransport — Support multitransport protocol (default: on)
-nego — protocol security negotiation (default: on)
/network:[invalid|modem|broadband|broadband-low|broadband-high|wan|lan|auto] — Network connection type
/nsc, /nscodec — NSCodec support
/orientation:[0|90|180|270] — Orientation of display in degrees
+old-license — Use the old license workflow (no CAL and hwId set to 0) (default: off)
/p[:password] — Password. Pass /p without arguments to silences interactive password prompts if no credentials are required for the connection.
/parallel[:name[,path]] — Redirect parallel device
/parent-window:window-id — Parent window id
/pcb:blob — Preconnection Blob
/pcid:id — Preconnection Id
/pheight:height — Physical height of display (in millimeters)
/play-rfx:pcap-file — Replay rfx pcap file
/port:number — Server port
-suppress-output — suppress output when minimized (default: on)
+print-reconnect-cookie — Print base64 reconnect cookie after connecting (default: off)
/printer[:name[,driver[,default]]] — Redirect printer device
/proxy:[proto://][user:password@]host[:port] — Proxy settings: override env. var (see also environment variable below). Protocol socks5 should be given explicitly where http is default.

and that's only part 1 bestie 😭 there's so much more coming — don't go anywhere.

/pth:password-hash, /pass-the-hash:password-hash — Pass-the-hash time ✨ (that's restricted admin mode, bestie)
/pwidth:width — physical width of the display, measured in millimeters 📏
/rdp2tcp:executable path[:arg...] — TCP redirection, go off
/reconnect-cookie:base64-cookie — hand a base64 reconnect cookie over to the connection 🍪
/redirect-prefer:FQDN|IP|NETBIOS,[...] — override the preferred redirection order, you get to pick the lineup
/relax-order-checks, /relax-order-checks — nope, it does not check whether an RDP order was announced during capability exchange. Only use this when you're connecting to a buggy server, fr fr 🙈
/restricted-admin, /restrictedAdmin — restricted admin mode, unlocked 🔐
/rfx — RemoteFX, that's it, that's the whole thing
/rfx-mode:[image|video] — RemoteFX mode, pick your flavor
/scale:[100|140|180] — scaling factor of the display (default: 100) 🦋
/scale-desktop:percentage — scaling factor for desktop applications, value lives between 100 and 500 (default: 100)
/scale-device:100|140|180 — scaling factor for app store applications (default: 100)
/sec:rdp[:[on|off]]|tls[:[on|off]]|nla[:[on|off]]|ext[:[on|off]]|aad[:[on|off]] — force a specific protocol security. Like, /sec:nla turns NLA on and turns everything else off, while /sec:nla:[on|off] just toggles NLA and leaves the rest alone 👑
/serial[:name[,path[,driver[,permissive]]]], /tty[:name[,path[,driver[,permissive]]]] — redirect a serial device
/server-name:name — the user-specified server name used for validation (TLS, Kerberos)
/shell:shell — alternate shell 🐚
/shell-dir:dir — shell working directory
/size:widthxheight or percent%[wh] — screen size (default: 1024x768)
/smart-sizing:widthxheight|on|off — scale the remote desktop to the window size (default: off)
/smartcard[:str[,str...]] — redirects the smartcard devices that have any of the str in their names 💳
/smartcard-logon[:[[cert:path|cert:base64(PEM)],[key:path|key:base64(PEM)],pin:pin,csp:csp name,reader:reader,card:card]] — activates Smartcard (with optional certificate) Logon authentication 🔥
/sound[:[sys:sys,][dev:dev,][format:format,][rate:rate,][channel:channel,][latency:latency,][quality:quality]], /audio[:[sys:sys,][dev:dev,][format:format,][rate:rate,][channel:channel,][latency:latency,][quality:quality]] — audio output (sound), make it loud 🔊
/span — span the screen across multiple monitors 🖥️
/spn-class:service-class — SPN authentication service class
/ssh-agent, /ssh-agent — SSH Agent forwarding channel
/sspi-module:SSPI module path — file path for the SSPI shared library module
/winscard-module:WinSCard module path — file path for the WinSCard shared library module
/disable-output — deactivates all graphics decoding in the client session. Genuinely useful for load tests with lots of simultaneous connections 💀
/t:title, /title:title — window title
-themes — themes (default: on)
/timeout:time in ms, /timeout:time in ms — advanced setting for high latency links: it adjusts the connection timeout, so use it if you're hitting timeout failures on your connection (default: 9000)
/timezone:windows timezone — uses the windows timezone you supply for the connection (server support required), peep /list:timezones for the allowed values 🌍
/tls:[ciphers|seclevel|secrets-file|enforce] — TLS configuration options, and here's the breakdown:
- ciphers:[netmon|ma|<cipher names>]
- seclevel:<level>, default: 1, range: [0-5] — overrides the default TLS security level, might be needed for older target servers. Deets at https://docs.openssl.org/3.0/man3/SSL_CTX_set_security_level/
- secrets-file:<filename>
- enforce[:[ssl3|1.0|1.1|1.2|1.3]] — forces the SSL/TLS version used for a connection. Some servers have buggy TLS version negotiation and will fail without this. Defaults to TLS 1.2 when you don't hand it an argument. Use 1.0 for windows 7
-toggle-fullscreen — Alt+Ctrl+Enter toggles fullscreen (default: on)
/tune:setting:value,setting:value — [experimental] directly manipulates freerdp settings, use with extreme caution! (default: )
/u:[[domain]user|user[@domain]] — username
+unmap-buttons — lets the server see the real physical pointer button (default: off)
/usb:[dbg,][id:vid:pid#...,][addr:bus:addr#...,][auto] — redirect a USB device 🔌
/v:server[:port] — server hostname|URL|IPv4|IPv6, or vsock://<number>, or /some/path/to/pipe, or |:1234 to pass a TCP socket to use
/vc:channel[,options] — static virtual channel
/version — print version 📜
/video — video optimized remoting channel
/prevent-session-lock[:time in sec] — prevents session locking by injecting fake mouse motion events to the server whenever the connection goes idle (default interval: 180 seconds) 🐭
/vmconnect[:vmid] — Hyper-V console (use port 2179, disable negotiation)
/w:width — width (default: 1024)
-wallpaper — wallpaper (default: on) 🖼️
+window-drag — full window drag (default: off)
/window-position:xposxypos — window position
/wm-class:class-name — sets the WM_CLASS hint for the window instance
/workarea — use the available work area

⌨️ KEYBOARD SHORTCUTS ⌨️

<Right CTRL> — releases the keyboard and mouse grab. If the keyboard is grabbed, your local system shortcuts stop working and get sent to the remote system instead. If the mouse is grabbed (which is optional), local gesture detection doesn't work and the mouse might not be able to leave the RDP window. Mouse events themselves are not altered, no cap.
<CTRL>+<ALT>+<Return> — toggles the fullscreen state of the application 🖥️✨
<CTRL>+<ALT>+<m> — minimizes the application
<CTRL>+<ALT>+c — toggles remote control in a remote assistance session 🎛️
<CTRL>+<ALT>+<d> — disconnects the session and terminates the application 💀
Action Script — executes a predefined script when you press a key. If the script doesn't exist, it's just ignored, no drama. Scripts can live at the default location $XDG_CONFIG_HOME/freerdp/action.sh, or you can hand one over as a command line argument: /action:script:<path>. The script receives the current key combination as its argument. The script's output is parsed for key-local, which tells you the script used the key combination — otherwise the combination gets forwarded to the remote 🧚

🌈 ENVIRONMENT VARIABLES 🌈

wlog environment variables — xfreerdp3 uses wLog as its log facility, so you can check out the matching man page (wlog(7)) for more info. Arguments passed through /log-level or /log-filters have precedence over the environment variables, bestie, they win 🏆
freerdp environment variables — all sorts of configurations for the core library can be set with environment variables too. Consult freerdp(7) for more info.
FREERDP_ASKPASS — sets a program to ask for passwords, similar to SSH_ASKPASS 🔑

💾 GLOBAL CONFIGURATION (client common) 💾

Format and Location

The configuration files are stored in the global system configuration.

The common certificate settings location is /etc/FreeRDP/certificates.json

File format is JSON ✨

Supported options

deny
- JSON boolean
- Deny the certificate if the check against the system SSL store was not successful
ignore
- JSON boolean
- Ignore certificate failures, just ignore the certificate entirely 🙈
deny-userconfig
- JSON boolean
- If the checks in the global configuration don't accept the certificate, don't ask the user
certificate-db
- JSON array
- An array of JSON objects with:
  - type
    - JSON string
    - a string identifying the hash algorithm used, e.g. sha256
  - hash
    - JSON string
    - a string of hex integer values representing the certificate hash, e.g. 0123456789abcdef

🎀 GLOBAL CONFIGURATION (X11 client) 🎀

The X11 client configuration location is /etc/FreeRDP/xfreerdp.json

File format is JSON

Supported options:

isActionScriptAllowed
- JSON boolean
- Allow or block action scripts. Default (if the option isn't set) is to allow action scripts 💅

🌈 EXAMPLES 🌈

okay bestie, this is the part where it all comes together. real-world receipts. no cap. 💖

#!/bin/bash

# we got a key combination
if [ "$1" = "key" ];
then
     # we only got one argument 'key'
     # list all supported combinations with echo
     if [ $# -eq 1 ];
     then
          echo "ctrl+alt+f1"
          echo "ctrl+alt+f2"
     else
          # We want the action for a single combination
          # use 'key-local' to not forward to RDP session
          if [ "$2" = "ctrl+alt+f1" ];
          then
               echo "key-local"
          fi
          if [ "$2" = "ctrl+alt+f2" ];
          then
                    echo "/usr/local/bin/somescript.sh"
          fi
     fi
fi
if [ "$1" = "xevent" ];
     then
          if [ $# -eq 1 ];
          then
               echo "FocusIn"
               echo "SelectionClear"
          else
               if [ "$2" = "SelectionNotify" ];
               then
                    echo "/usr/local/bin/someprogram"
               fi
          fi
     fi

Example action script for key events, listing ctrl+alt+f1 to be handled by local window manager and ctrl+alt+f2 executing a script.

✨ the return value of the program determines if the key is handled locally or remotely (0 for local, > 0 for remote, < 0 for errors)

xfreerdp3 connection.rdp /p:Pwd123! /f — connect in fullscreen mode using a stored configuration connection.rdp and the password Pwd123! 🖥️
xfreerdp3 /u:USER /size:50%h /v:rdp.contoso.com — connect to host rdp.contoso.com with user USER and a size of 50 percent of the height. If width (w) is set instead of height (h) like /size:50%w, then 50 percent of the width is used. 📐
xfreerdp3 /u:CONTOSO\\JohnDoe /p:Pwd123! /v:rdp.contoso.com — connect to host rdp.contoso.com with user CONTOSO\\JohnDoe and password Pwd123! 🔐
xfreerdp3 /u:JohnDoe /p:Pwd123! /w:1366 /h:768 /v:192.168.1.100:4489 — connect to host 192.168.1.100 on port 4489 with user JohnDoe, password Pwd123!. The screen width is set to 1366 and the height to 768 📏
xfreerdp3 /u:JohnDoe /p:Pwd123! /vmconnect:C824F53E-95D2-46C6-9A18-23A5BB403532 /v:192.168.1.100 — establish a connection to host 192.168.1.100 with user JohnDoe, password Pwd123! and connect to Hyper-V console (use port 2179, disable negotiation) with VMID C824F53E-95D2-46C6-9A18-23A5BB403532 🧚
+clipboard — activate clipboard redirection 📋
/drive:home,/home/user — activate drive redirection of /home/user as home drive 💾
/smartcard:<device> — activate smartcard redirection for device device 🎀
/printer:<device>,<driver> — activate printer redirection for printer device using driver driver 🖨️
/serial:<device> — activate serial port redirection for port device 🔌
/parallel:<device> — activate parallel port redirection for port device 🧵
/sound:sys:alsa — activate audio output redirection using device sys:alsa 🔊
/microphone:sys:alsa — activate audio input redirection using device sys:alsa 🎤
/multimedia:sys:alsa — activate multimedia redirection using device sys:alsa 🎬
/usb:id,dev:054c:0268 — activate USB device redirection for the device identified by 054c:0268 🍓
/kbd:remap:29=58,remap:58=29 — swap left Control (29) and Caps Lock (58). 🔥

💫 LINKS 💫

http://www.freerdp.com/ — that's the site, bestie. go look. 🦋

👑 AUTHOR 👑

The FreeRDP Team — absolute icons, no notes. 💅

and that's the whole page, babes!! 🫶 this version of xfreerdp3(1) comes from the freerdp source and it's dated 2026-10-05. go forth and remote desktop like the main character you are. periodt. 🌸✨👑

📦 where this page comes from

ubuntu noble: freerdp3-x11 3.32.1+dfsg-0ubuntu0.24.04.1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms