xfreerdp(1)

📦
version 3.32.2 · 18 versions
, in fedora 43, fedora 44

💖 xfreerdp — the manual, but make it cute 💖

okay bestie, so you wanna RDP into a Windows box from your X11 setup? say less. this is xfreerdp, section 1 of the manual, aka the FreeRDP X11 client, and she understands you. let's get into it 🫶

✨ NAME ✨

xfreerdp — FreeRDP X11 client. short. sweet. iconic. periodt 💅

🦋 SYNOPSIS 🦋

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

that's the whole vibe. file? optional. options? as many as your heart desires. server? you need that one, [/v:server[:port]], don't forget her 🎀

🌸 DESCRIPTION 🌸

xfreerdp is an X11 Remote Desktop Protocol (RDP) client which is part of the FreeRDP project.

and like, RDP servers? literally built-in to so many editions of Windows already, no setup required. but if Windows servers aren't your thing, alternative servers include ogon, gnome-remote-desktop, xrdp and VRDP (VirtualBox). options, we love to see it 🌈

👑 OPTIONS 👑

okay here comes the big list. she's long. she's thorough. she's highkey the main character. every flag, every default, every argument — all of it, right here 💜

  • /a:addin[,options], /addin:addin[,options] — Addin. that's the entire blurb bestie, she's giving mysterious 🕵️
  • /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. all the cloud girlies, this one's for you ✨
  • /action-script:file-name — Action script (default:~/.config/freerdp/action.sh)
  • /admin, /console — Admin (or console) session. no cap, sometimes you just need the keys 👑
  • +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] — the manpage gives this one no blurb at all, so here she is in all her unbothered, mysterious glory 🙈
  • /cert:[deny,ignore,name:name,tofu,fingerprint:hash:hash as hex[,fingerprint:hash:another hash]] — Certificate accept options. Use with care!
⚠️ bestie. use with care. this is the part where you read everything, okay? 😭
  • 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, she's listed twice. the manpage said it, not me 💀)
  • -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:..., /gw:... — Gateway Hostname. full syntax, verbatim, because she is long:
/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
  • /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],frame-ack[:on|off],AV1[:on|off|i444|i420]]] — 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 keybouard layout announced to the server (yes, "keybouard" — typo is canon, don't @ me)
    • 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

and that's only part one bestie, we're literally just getting started 🌸 more coming 💖

  • /proxy:[proto://][user:password@]host[:port] — proxy time, bestie 🌐 this overrides the env var (scroll down for the environment variable tea ☕). and heads up: socks5 has to be said out loud explicitly, because http is the default and it will not read your mind.
  • /pth:password-hash, /pass-the-hash:password-hash — pass the hash (restricted admin mode) 🔑
  • /pwidth:width — physical width of the display, in millimeters 📏
  • /rdp2tcp:executable path[:arg...] — TCP redirection 🔀
  • /reconnect-cookie:base64-cookie — hands a base64 reconnect cookie over to the connection 🍪
  • /redirect-prefer:FQDN|IP|NETBIOS,[...] — overrides the preferred redirection order ✨
  • /relax-order-checks, /relax-order-checks — do not check whether an RDP order was announced during capability exchange. literally only use this when you're connecting to a buggy server, no cap 💀 (and yes it's written twice, that's just how it came, we keep it real)
  • /restricted-admin, /restrictedAdmin — restricted admin mode 🛡️
  • /rfx — RemoteFX ✨
  • /rfx-mode:[image|video] — RemoteFX mode 🎬
  • /scale:[100|140|180] — scaling factor of the display (default:100) 🔍
  • /scale-desktop:percentage — scaling factor for desktop applications, value 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, periodt. like /sec:nla turns NLA on and switches everything else off, while /sec:nla:[on|off] just toggles NLA on its own 🔐
  • /serial[:name[,path[,driver[,permissive]]]], /tty[:name[,path[,driver[,permissive]]]] — redirect a serial device 🔌
  • /server-name:name — user-specified server name to use 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 (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) 🔊
  • /span — span the screen over multiple monitors 🖥️🖥️
  • /spn-class:service-class — SPN authentication service class 🎫
  • /ssh-agent, /ssh-agent — SSH Agent forwarding channel 🔑
  • /sspi-module:SSPI module path — SSPI shared library module file path 📚
  • /winscard-module:WinSCard module path — WinSCard shared library module file path 🃏
  • /disable-output — deactivates all graphics decoding in the client session. lowkey perfect for load tests with a ton of simultaneous connections 👑 (it's giving "I don't need to see it, I just need it to run")
  • /t:title, /title:title — window title 🪧
  • -themes — themes (default:on) 🎨
  • /timeout:time in ms, /timeout:time in ms — advanced setting for high latency links: adjusts the connection timeout. use this if you keep getting timeout failures on your connection (default:9000) ⏱️
  • /timezone:windows timezone — use the supplied windows timezone for the connection (requires server support), peep /list:timezones for the allowed values 🌍
  • /tls:[ciphers|seclevel|secrets-file|enforce] — TLS configuration options 💅:
    • 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. details 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 use of an SSL/TLS version for a connection. some servers have a buggy TLS version negotiation and might straight up fail without this. defaults to TLS 1.2 if no argument is supplied. use 1.0 for windows 7 🪟
  • -toggle-fullscreen — Alt+Ctrl+Enter to toggle 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,][filter:class#...|none] — 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 is 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 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 (optional), local gesture detection doesn't work and the mouse might not be able to leave the RDP window. mouse events are not altered, fr fr.
  • 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 on key press 🎬. if the script doesn't exist, it's just ignored, no biggie. scripts can live at the default location $XDG_CONFIG_HOME/freerdp/action.sh, or you can pass them as a command line argument /action:script:<path>. the script gets the current key combination as its argument. the output of the script 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 — xfreerdp uses wLog as its log facility, so you can hit up the corresponding man page (wlog(7)) for more info 📖. arguments passed via /log-level or /log-filters take precedence over the environment variables, periodt.
  • freerdp environment variables — various configurations of the core library can be configured with environment variables too. consult freerdp(7) for more info 🧠.
  • FREERDP_ASKPASS — set a program to ask for passwords, similar to SSH_ASKPASS 🔑.

💖 GLOBAL CONFIGURATION (client common) 💖

Format and Location:

  • the configuration files are stored in 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 🙈
  • deny-userconfig — JSON boolean
    • if the checks in the global configuration do not accept the certificate, do not 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 🎬. the default (when the option is not set) is to allow action scripts 🫶

✨ EXAMPLES ✨

Okay bestie, this is the part where it all clicks, I promise 💖 Strap in, we're doing real commands now.

First up, a little action script for key events — like, the whole reason you'd want key-local and xevent in your life at all:

#!/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

So that's an example action script for key events — it lists ctrl+alt+f1 as something the local window manager should handle, and ctrl+alt+f2 as something that runs a script. Iconic behaviour, honestly 🎀

And the plot twist you need to know: the return value of the program is what decides if the key gets handled locally or remotely — 0 for local, > 0 for remote, < 0 for errors. Periodt. No cap, that's the whole decision tree.

Now the actual xfreerdp invocations, one by one 🦋

xfreerdp connection.rdp /p:Pwd123! /f

Connect in fullscreen mode using a stored configuration connection.rdp and the password Pwd123!. Chef's kiss — config file does the heavy lifting, you just vibe.

xfreerdp /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. And listen — if you set width (w) instead of height (h), like /size:50%w, then 50 percent of the width gets used. Pick your percentage poison 💅

xfreerdp /u:CONTOSO\\JohnDoe /p:Pwd123! /v:rdp.contoso.com

Connect to host rdp.contoso.com with user CONTOSO\\JohnDoe and password Pwd123!. Domain-flavoured username, love that for you 🌸

xfreerdp /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. Very specific, very demure 💖

xfreerdp /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. That's a whole UUID, bestie, we're in the Hyper-V-iverse now 😭

+clipboard

Activate clipboard redirection. Copy-paste across worlds, we love to see it 🫶

/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). Absolute chaos, but make it a keymap 🔥

👑 AUTHOR 👑

The FreeRDP Team wrote all of this. Legends, every one of them, fr fr 💜

And that's a wrap on xfreerdp(1)! 🌈 This little masterpiece comes from the freerdp source, version-dated 2026-10-14, and it's living its best life under the name xfreerdp(1). Go forth and remote-desktop responsibly, bestie — you've got this 💅✨🎀

📦 where this page comes from