├── .gitignore ├── Configuration ├── FreeRDP-Configuration-Manual.markdown └── FreeRDP-Configuration-Manual.pdf ├── Developer ├── FreeRDP-Developer-Manual.markdown └── FreeRDP-Developer-Manual.pdf ├── Testing ├── FreeRDP-Testing-Manual.markdown └── FreeRDP-Testing-Manual.pdf ├── User ├── FreeRDP-User-Manual.markdown ├── FreeRDP-User-Manual.pdf └── images │ ├── freerdp_multitouch.png │ ├── freerdp_print_cups_pdf.png │ ├── freerdp_serial_redirection.png │ ├── language_bar.png │ ├── linux_registry.png │ ├── mstsc_help.png │ ├── windows_registry.png │ ├── winlogon_gui.png │ ├── with_smooth_fonts.png │ ├── with_themes.png │ ├── without_smooth_fonts.png │ └── without_themes.png └── gen.pl /.gitignore: -------------------------------------------------------------------------------- 1 | 2 | *~ 3 | .DS_Store 4 | 5 | -------------------------------------------------------------------------------- /Configuration/FreeRDP-Configuration-Manual.markdown: -------------------------------------------------------------------------------- 1 | % FreeRDP Configuration Manual 2 | % Marc-André Moreau 3 | % Awake Coding Consulting Inc. 4 | 5 | # Introduction 6 | 7 | This document specifies various configuration procedures for common RDP deployment scenarios. These instructions should be used as a reference to help RDP developers configure a proper test setup to help them in their implementation. 8 | 9 | ## Glossary 10 | 11 | To be expanded. 12 | 13 | ## References 14 | 15 | [FreeRDP User Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/User/FreeRDP-User-Manual.pdf?raw=true "FreeRDP User Manual") 16 | 17 | [FreeRDP Developer Manual](https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/master/Developer/FreeRDP-Developer-Manual.pdf?raw=true "FreeRDP Developer Manual") 18 | 19 | [FreeRDP Testing Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Testing/FreeRDP-Testing-Manual.pdf?raw=true "FreeRDP Testing Manual") 20 | 21 | # Network Tracing 22 | 23 | ## Introduction 24 | 25 | Network tracing of RDP can be quite a challenge due to a number of factors such as encryption, compression, and the fact that these protocol features cannot always be disabled or worked around. One of the easiest way of decrypting RDP traffic is to configure the server with a self-signed certificate for which the private key is known, and then use this certificate with a network tracing tool to automatically decrypt the packets. 26 | 27 | ## Certificate Generation 28 | 29 | The following sections specify how to generate valid certificates that can be used with an RDP server. 30 | 31 | ### WinPR 32 | 33 | For the sake of simplicity, a replacement of the commonly used "makecert" tool has been implemented as part of the WinPR tools as winpr-makecert. The tool offers the same command-line interface as the original makecert and can generate valid RDP certificates. 34 | 35 | In the FreeRDP source tree, the winpr-makecert executable can be found in winpr/tools/makecert/cli. The core of the winpr-makecert tool is built as a reusable library which is used by many of the FreeRDP-based servers for automatic generation of a self-signed certificate when no other certificate was previously installed. 36 | 37 | The flexibility of an open source makecert replacement usable as both a redistributable excutable or an embeddedable library is such that third parties who implement solutions that have nothing to do with RDP may still want to use it. 38 | 39 | To generate a default self-signed RDP certificate, use the -rdp option: 40 | 41 | winpr-makecert -rdp 42 | 43 | Information regarding the generated certificate will be shown. The certificate and private key files will be outputted in the current working directory with a name that matches the current machine's hostname. In this case, my machine's name is "system76", so the generated files are system76.crt and system76.key. 44 | 45 | A non-default file output name can be specified using the last command-line argument: 46 | 47 | winpr-makecert -rdp server 48 | 49 | In this case, winpr-makecert will name the files server.crt and server.key. 50 | 51 | The files generated by winpr-makecert are readily usable by the FreeRDP servers but need to be converted to pfx for usage with the Microsoft RDP server. Please consult the section of this manual on certificate conversion to learn how this can be done. 52 | 53 | ### MakeCert 54 | 55 | MakeCert is a tool that is included with the Windows SDK or the Windows DDK that can generate certificates in the pfx file format. 56 | 57 | If you have the Windows DDK installed, makecert.exe can be found at: 58 | 59 | \WinDDK\\bin\\makecert.exe 60 | 61 | If you have the Windows SDK installed, makecert.exe can be found at: 62 | 63 | %programfiles%\Microsoft SDKs\Windows\\bin\makecert.exe 64 | 65 | MakeCert is currently not distributed separately from the Windows DDK or the Windows SDK. Since it is a small and stand-alone tool, it can be easily copied to another machine without the need for installing large software development packages. Keeping a copy for later use can therefore save a lot of time when configuring new machines. 66 | 67 | To generate a self-signed certificate, invoke MakeCert with the following options: 68 | 69 | makecert -r -pe -n "CN=%COMPUTERNAME%" -eku 1.3.6.1.5.5.7.3.1 -ss my -sr LocalMachine -sky exchange -sp "Microsoft RSA SChannel Cryptographic Provider" -sy 12 70 | 71 | %COMPUTERNAME% expands to the current computer name, which is normally what you want. The name following “CN=” should be the common name of the certificate. Choose it wisely, because a certificate for which the common name attribute does not match the hostname that the client uses to connect is normally rejected. 72 | 73 | MakeCert generates and import the certificate automatically, so do not expect to find a certificate file in the directory from which MakeCert has been executed. To get the certificate file, you will need to export it from the certificate store. 74 | 75 | * Launch MMC as an elevated user (can be done from an Administrator command prompt) 76 | * On the File menu, click Add/Remove Snap-in 77 | * In the left pane, select Certificates, then click Add 78 | * When prompted for user account type, select Computer account and click Next 79 | * In the next dialog, leave Local computer as the computer to manage and click Finish 80 | * Close the Add or Remove Snap-Ins dialog by clicking OK 81 | * In the left pane, expand Certificates (Local Computer) 82 | * Under Certificates (Local Computer), expand Personal and then select the Certificates directory 83 | * In the right pane, you should find your newly generated self-signed certificate. Right-click on it, point to All Tasks, then click Export. The Certificate Export Wizard will appear. 84 | * In the welcome screen, click Next 85 | * In the Export Private Key screen, select Yes, export private key and click Next 86 | * In the Export File Format screen, select Include all certificates in the certification path if possible and Export all extended properties, and click Next 87 | * In the Password screen, enter a password which you will need to use when importing the certificate after it has been exported, and then click Next. The password is used to protect the private key. For testing purposes, you may want to use a simple dummy password such as “password”. 88 | * In the File to Export screen, specify a path and file name for the certificate to be exported. Click Next, and then Finish. A message box should indicate that the certificate has been successfully exported. 89 | 90 | ### OpenSSL 91 | 92 | Create an OpenSSL extension file named “rdp.ext” 93 | 94 | extensions = x509v3 95 | 96 | [ x509v3 ] 97 | keyUsage = keyEncipherment,dataEncipherment 98 | extendedKeyUsage = serverAuth 99 | 100 | Create an OpenSSL config file named “rdp.cfg”: 101 | 102 | [ req ] 103 | default_bits = 2048 104 | distinguished_name = req_DN 105 | string_mask = nombstr 106 | 107 | [ req_DN ] 108 | countryName = "1. Country Name (2 letter code)" 109 | countryName_default = CA 110 | countryName_min = 2 111 | countryName_max = 2 112 | stateOrProvinceName = "2. State or Province Name (full name) " 113 | stateOrProvinceName_default = Quebec 114 | localityName = "3. Locality Name (eg, city) " 115 | localityName_default = Montreal 116 | 0.organizationName = "4. Organization Name (eg, company) " 117 | 0.organizationName_default = Awake Coding Consulting Inc. 118 | organizationalUnitName = "5. Organization Unit Name (eg, section) " 119 | commonName = "6. Common Name (CA name or FQDN)" 120 | commonName_max = 64 121 | commonName_default = awakecoding.com 122 | emailAddress = "7. Email Address (eg, name@FQDN) " 123 | emailAddress_max = 40 124 | emailAddress_default = admin@awakecoding.com 125 | 126 | Execute the following commands in the directory where rdp.ext and rdp.cfg are located: 127 | 128 | openssl genrsa –out rdp.key 2048 129 | openssl req -config rdp.cfg -new -key rdp.key -out rdp.csr 130 | openssl x509 -req -days 365 -extfile rdp.ext -signkey rdp.key -in rdp.csr -out rdp.crt 131 | openssl pkcs12 -export -inkey rdp.key -in rdp.crt -out rdp.pfx 132 | 133 | ## Certificate Conversion 134 | 135 | Convert from pfx to crt using OpenSSL: 136 | 137 | openssl pkcs12 -in rdp.pfx -clcerts –nodes -out rdp.crt 138 | 139 | Convert from crt to pfx using OpenSSL: 140 | 141 | openssl pkcs12 -export –in rdp.crt -inkey rdp.key –nodes -out rdp.pfx 142 | 143 | Some tools like Network Monitor's decryption export require a .pfx certificate with a password. To convert from crt to pfx while adding a password, leave the -nodes option out: 144 | 145 | openssl pkcs12 -export –in rdp.crt -inkey rdp.key -out rdp.pfx 146 | 147 | ## Certificate Installation 148 | 149 | Import the certificate: 150 | 151 | * Launch MMC as an elevated user (can be done from an Administrator command prompt) 152 | * On the File menu, click Add/Remove Snap-in 153 | * In the left pane, select Certificates, then click Add 154 | * When prompted for user account type, select Computer account and click Next 155 | * In the next dialog, leave Local computer as the computer to manage and click Finish 156 | * Close the Add or Remove Snap-Ins dialog by clicking OK 157 | * In the left pane, expand Certificates (Local Computer) 158 | * Under Certificates (Local Computer), expand Personal 159 | * Right-click Personal, point to All Tasks and click Import. The Certificate Import Wizard will appear. 160 | * In the welcome screen, click Next 161 | * In the File to Import screen, specify the path to certificate file to import, and click Next 162 | * In the Password screen, enter the password that was used to export the certificate, select Mark this key as exportable, and click Next 163 | * In the Certificate Store screen, select Place all certificates in the following store and select the Personal certificate store. Click Next and then Finish. A message box should indicate that the certificate has been successfully imported, and the certificate should now appear in the Personal certificate store. 164 | 165 | ### Terminal Server 166 | 167 | #### Windows Server 2008 168 | 169 | Configure RDP server to use certificate: 170 | * Launch the Server Manager 171 | * In the left pane, expand Roles, Remote Desktop Services, and then select RD Session Host Configuration 172 | * In the middle pane, right-click the connection to configure, such as “RDP-Tcp” and select Properties. The Connection Properties dialog will appear. 173 | * In the General tab, click Select. A list of usable certificates will appear, select the appropriate one and click OK. 174 | * Click OK to apply the changes and close the Connection Properties dialog 175 | 176 | #### Windows 7 177 | 178 | Configure certificate permissions: 179 | 180 | * Right-click on the certificate, point to All Tasks and click Manage Private Keys 181 | * In the Permissions for private keys dialog, click Add 182 | * In the Select Users or Groups dialog, type NETWORK SERVICE and click Check Names. Once the NETWORK SERVICE text is underlined, click OK 183 | * In the Permissions for private keys dialog, click OK 184 | 185 | Obtain certificate thumbprint: 186 | 187 | * Double-click on the certificate. A Certificate dialog will appear. 188 | * Select the Details tab, and select Thumbprint from the list of fields. Th thumbprint will be shown in the bottom text box as a series of hexadecimal numbers. Save the thumbprint for later as it is needed to configure the RDP server to use the certificae. The thumbprint should look like "a6 ff 13 00 b5 47 85 bf 48 3d 70 74 c8 aa 23 bb 3f 19 c1 71". 189 | 190 | Configure RDP server to use certificate: 191 | 192 | * Launch the Registry Editor (regedit.exe) 193 | * In the directory structure, browse to the following key:[HKEY_LOCAL_MACHINE\\System\\CurrentControlSet\\Control\\Terminal Server\\WinStations\\RDP-Tcp] 194 | * Right-click the RDP-Tcp key, point to New and click Binary Value. Name the new key SSLCertificateSHA1Hash 195 | * Right-click the SSLCertificateSHA1Hash key and click Modify Binary Data. In the Edit Binary Data dialog, type the thumbprint of the certificate to be used by the RDP server. As it is particularly easy to make a mistake in this step, double-check that you have entered the thumbprint properly, and click OK 196 | 197 | The RDP server should now be configured to use the new certificate. 198 | 199 | ### TS Gateway 200 | 201 | * Launch the Server Manager 202 | * In the left pane, expand Roles, Remote Desktop Services and then RD Gateway Manager 203 | * Under RD Gateway Manager, right-click the current server and click Properties to open the RD Gateway Server Properties dialog. 204 | + In the SSL Certificate tab, click Import Certificate to open the Import Certificate dialog. 205 | + From the list of certificates, select the one which you want to use, and click Import 206 | + Click OK to close the RD Gateway Server Properties dialog. A message box should inform you that the RD Gateway Server server needs to be restarted for the changes to take effect. 207 | 208 | ## Protocol Configuration 209 | 210 | Certain protocol features such as encryption and compression can make packet analysis harder. 211 | 212 | ### TLS 1.0 213 | 214 | Recent versions of Windows like Windows 8 will negotiate TLS 1.2 by default, a version of TLS which is not supported by Network Monitor. For easier packet decryption, it is recommended to force TLS 1.0 to be negotiated by disabling TLS 1.1 and TLS 1.2 on clients that support it. 215 | 216 | #### Disabling TLS 1.1 217 | 218 | [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Client] 219 | "Enabled"=dword:00000000 220 | "DisabledByDefault"=dword:00000001 221 | 222 | [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.1\Server] 223 | "Enabled"=dword:00000000 224 | "DisabledByDefault"=dword:00000001 225 | 226 | #### Disabling TLS 1.2 227 | 228 | [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\\Client] 229 | "Enabled"=dword:00000000 230 | "DisabledByDefault"=dword:00000001 231 | 232 | [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols\TLS 1.2\Server] 233 | "Enabled"=dword:00000000 234 | "DisabledByDefault"=dword:00000001 235 | 236 | ### UDP Transport 237 | 238 | On Windows 8 and newer, disable UDP transport: 239 | 240 | [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client] 241 | "DisableUDPTransport"=dword:00000001 242 | 243 | ### Compression 244 | 245 | To disable compression with mstsc, create a .rdp file and use the following option: 246 | 247 | compression:i:0 248 | 249 | With FreeRDP, simply do not turn on compression, or explicitly turn it off either with a .rdp file or with the –compression command-line option. 250 | 251 | If you want to force a specific version of the compression, the MaxRdpCompressionLevel registry key can be used: 252 | 253 | [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Terminal Server Client] 254 | "MaxRdpCompressionLevel"=dword:00000000 255 | 256 | | MaxRdpCompressionLevel | Protocol Version | 257 | |------------------------|-------------------| 258 | | 0 | RDP4 (8K) | 259 | | 1 | RDP5 (64K) | 260 | | 2 | RDP6 (64K NCRUSH) | 261 | | 3 | RDP6.1 (XCRUSH) | 262 | | 4 | RDP8 | 263 | 264 | ### RDP Security 265 | 266 | When using RDP security, lowering the encryption level may be useful: 267 | 268 | [HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Microsoft\Windows NT\Terminal Services] 269 | "MinEncryptionLevel"=dword:00000001 270 | 271 | | Value | Level | 272 | |-------|--------| 273 | | 0 | Low | 274 | | 1 | Medium | 275 | | 2 | High | 276 | 277 | ### Network Level Authentication 278 | 279 | To disable NLA with mstsc, create a .rdp file and use the following option: 280 | 281 | enablecredsspsupport:i:0 282 | 283 | To disable NLA with FreeRDP, you can use either the .rdp file or the –sec-nla command-line option. 284 | 285 | ## Packet Capturing 286 | 287 | There are two major packet capturing tools that can be used to capture RDP traffic: Network Monitor and Wireshark. The former has the advantage of being able to analyze a lot of the protocols of interest, but is not supported on non-Windows environments. The latter is open source and is supported on a wide variety of operating systems, but lacks good protocol analyzers for the vast majority of RDP. 288 | 289 | ### Message Analyzer 290 | 291 | Message Analyzer is Microsoft's replacement for the older Network Monitor tool. At the time of writing these lines, Message Analyzer is still only a beta, but it shows a lot of potential. Unlike Network Monitor, it will support live analysis. It also replaces Network Monitor's Network Parser Language (NPL) with the new Open Parser Notation (OPN) which is superior is many aspects. For instance, Message Analyzer will enable extremely precise filters based on protocol message sequencing. The usage of a parser language such as OPN also makes writing new parsers vastly easier than Wireshark, which uses an impractical C API for parsing. 292 | 293 | Message Analyzer is currently available on the [Message Analyzer Connect Site](https://connect.microsoft.com/site216 "Message Analyzer Connect Site") 294 | 295 | For further information, refer to the [Microsoft Message Analyzer Operating Guide](http://technet.microsoft.com/en-us/library/jj649776.aspx "Microsoft Message Analyzer Operating Guide") 296 | 297 | ### Network Monitor 298 | 299 | #### Installation 300 | 301 | Download and install required tools: 302 | 303 | * Network Monitor http://blogs.technet.com/b/netmon/ 304 | * NMParsers http://nmparsers.codeplex.com/ 305 | * NMDecrypt http://nmdecrypt.codeplex.com/ 306 | 307 | Change default parser profile: 308 | 309 | * Launch Network Monitor 310 | * On the Tools menu, click Options 311 | * In the Parsers Profile tab, select Windows and click OK 312 | 313 | #### Capturing 314 | 315 | * Launch Network Monitor 316 | * Click New Capture on the top menu bar 317 | * Click Start on the top menu bar. This may take a few seconds, wait until the Stop button becomes enabled. 318 | * Perform tasks generating network traffic of interest, and click Stop on the top menu bar 319 | 320 | ### Wireshark 321 | 322 | #### Installation 323 | 324 | Download and install Wireshark (http://www.wireshark.org/) 325 | If you are using Linux, it packages should be available for all major distributions. 326 | If you choose to build Wireshark from source, make sure that you are building with SSL support. 327 | 328 | #### Compilation 329 | 330 | This step is only required if the wireshark package that comes with your distribution is not built with proper SSL support (certain versions of openSUSE, for instance). If this is the case, the SSL dissector will lack necessary configuration options. 331 | 332 | Building is straightforward. Download and extract the latest wireshark sources. Install required build dependencies (libpcap-devel, libgnutls-devel). Configure with an isolated installation prefix, and enable ssl support, and then build and install: 333 | 334 | ./configure --prefix=/opt/wireshark --with-ssl=yes 335 | make install 336 | 337 | #### Configuration 338 | 339 | Configure SSL dissector: 340 | 341 | * Launch Wireshark 342 | * On the Edit menu, click Preferences 343 | * In the left pane, expand Protocols and select SSL 344 | * In the right pane, click Edit besides RSA keys list 345 | * In the SSL Decrypt dialog, click New 346 | * In the SSL Decrypt: New dialog, enter the following: 347 | + IP address of the RDP server 348 | + Port used by the RDP server 349 | + Protocol dissector to use with decrypted packets. When in doubt, use the data dissector. 350 | + Full path to the SSL private key file (.key extension) 351 | + Password used to protect the private key file, if there is one. 352 | * Click OK to get back to the SSL Decrypt dialog, and click OK again 353 | 354 | #### Capturing 355 | 356 | Capture traffic: 357 | 358 | * Launch Wireshark 359 | * On the Capture menu, click Interfaces 360 | * In the Capture Interfaces dialog, click Options besides the interface to capture from. If you do not know which interface to choose, it is normally the one with the highest amount of traffic as indicated in the Packets column. 361 | * In the Capture Options dialog, type port 3389 in the Capture Filter field. The filter may be different depending on the port(s) used by the server. Filtering the capture is optional, but helps filtering out packets which are not of interest. 362 | * Click Start 363 | * Perform tasks generating network traffic of interest, and click Stop either from the top menu bar or on the Capture menu 364 | 365 | # Users and Groups 366 | 367 | ## Adding Users 368 | 369 | ### Windows Server 2008 370 | 371 | #### Local Users 372 | 373 | * Launch the Server Manager 374 | * In the left pane, expand Configuration and then Local Users and Groups 375 | * Under Local Users and Groups, right-click Users and click New User. The New User dialog will appear. 376 | + Enter a username such as “jsmith” in the User name field 377 | + Enter a name such as “John Smith” in the Full name field 378 | + Enter a password such as “Password123!” in the Password and Confirm password fields 379 | + Unselect User must change password at next logon 380 | + Optionally select Password never expires (easier for testing) 381 | + Click Create to create the user 382 | + Click Close to close the dialog 383 | * Under Local Users and Groups, click Users to show the list of users in the right pane 384 | * In the right pane, right-click the user and then click Properties (“jsmith” from the previous example). The User Properties dialog will appear. 385 | + Under the Member Of tab, click Add. The Select Groups dialog will appear. 386 | + In the Enter the object names to select field, enter “Remote Desktop Users” and click Check Names. When the text becomes underlined, click OK. 387 | * Click OK in the User Properties dialog to close it 388 | 389 | #### Domain Users 390 | 391 | * Launch the Server Manager 392 | * In the left pane, expand Roles, Active Directory Domain Services, and then Active Directory Users and Computers. 393 | * Under Active Directory Users and Computers, right-click a domain such as “lab1.awake.local”, point to New and click User. The New Object – User dialog will appear. Complete the form and click Next: 394 | + First name: “John” 395 | + Last name: “Smith” 396 | + Full name: “John Smith” 397 | + User logon name: “jsmith” 398 | + User Logon name (pre-Windows 2000): “jsmith” 399 | * In the Password and Confirm password fields, enter a password like “Password123!” 400 | * Unselect User must change password at next logon, select Password never expires and then click Next 401 | * Click Finish 402 | 403 | # Active Directory 404 | 405 | ## Server Configuration 406 | 407 | ### Windows Server 2008 408 | 409 | Installing the Active Directory Domain Services Role: 410 | 411 | * Launch the Server Manager 412 | * In the left pane, click Roles 413 | * In the right pane, click Add Roles to launch the Add Roles wizard 414 | * If the Before you begin page appears, click Next 415 | * On the Server Roles page, select Active Directory Domain Services and click Next 416 | * On the Introduction to Active Directory Domain Services page, click Next 417 | * If prompted to add features required for the role, click Add Required Features 418 | * On the Confirm Installation Selections page, click Install 419 | * Wait for the Installation Results page to appear, click Close and reboot if necessary to complete the installation process. 420 | 421 | Promoting the server to a domain controller: 422 | 423 | 424 | * Click Start, click Run, type dcpromo and then click OK 425 | * This starts the Active Directory Installation Wizard. Click Next 426 | * On the Operating Systems Compatibility page, click Next 427 | * On the Choose a Deployment Configuration, select Create a new domain in a new forest and click Next 428 | * On the Name the Forest Root Domain page enter a FQDN such as “lab1.awake.local” and click Next. For testing purposes, avoid using a name which could potentially conflict with other existing names. Using the “.local” suffix is a good way to avoid conflicts. 429 | * On the Set Forest Functional Level page, select the desired forest functional level from the list and then click Next. If you do not intend to have backwards compatibility in a particular lab environment, you may select the highest functional level, such as Windows Server 2008 R2. 430 | * On the Add Domain Controller Options page, leave the DNS server option selected and click Next 431 | * A dialog box will appear warning that a delegation for the DNS server cannot be created. Ignore this warning and click Yes. 432 | * On the Location for Database, Log Files, and SYSVOL page, click Next 433 | * On the Directory Services Restore Mode Administrator Password enter a password such as “Password123!” and then click Next 434 | * On the Summary page, review the information and then click Next. Optionally, the summary information can be saved to a text file by clicking Export settings. 435 | * Wait for installation to complete. You may select Reboot on completion, or click Finish manually later. In both cases, the server needs to be rebooted before continuing further. 436 | 437 | Installing the Active Directory Certificate Services and DHCP Server roles: 438 | 439 | 440 | * Launch the Server Manager 441 | * In the left pane, click Roles 442 | * In the right pane, click Add Roles to launch the Add Roles wizard 443 | * If the Before you begin page appears, click Next 444 | * On the Server Roles page, select Active Directory Certificate Services and DHCP Server and then click Next 445 | * On the Introduction to DHCP Server page, click Next 446 | * On the Select Network Connection Bindings page, the server’s static IP address (“192.168.56.10”) should be listed and selected by default. Click Next to continue 447 | * On the Specify IPv4 DNS Server Settings page, enter the parent domain (“lab1.awake.local”) and the preferred DNS server IPv4 address. By default this address is 127.0.0.1, but it needs to be changed to the current server’s address (“192.168.56.10”). An alternate DNS server IPv4 address can also be entered. Click Next. 448 | * On the Specify IPv4 WINS Server Settings page, select WINS is required for applications on this network and enter the current server’s address (“192.168.56.10”) in the Preferred WINS server IP address field. Click Next. 449 | * On the Add or Edit DHCP Scopes page, click Add and enter the following information in the Add Scope dialog, click OK and then Next: 450 | + Scope name: “lab01” (or any descriptive name) 451 | + Starting IP address: 192.168.56.101 452 | + Ending IP address: 192.168.56.254 453 | + Subnet type: Wired (lease duration will be 8 days) 454 | + Leave Activate this scope selected 455 | + Subnet mask: 255.255.255.0 456 | + Default gateway (optional): 192.168.56.1 457 | * On the Configure DHCPv6 Stateless Mode page, select Disable DHCPv6 stateless mode for this server and click Next 458 | * On the Authorize DHCP Server page, select Use current credentials and click Next 459 | * On the Introduction to Active Directory Certificate Services page, click Next 460 | * On the Select Role Services page, select Certification Authority and click Next 461 | * On the Specify Setup Type page, select Standalone and click Next 462 | * On the Specify CA Type page, select Root CA and click Next 463 | * On the Set Up Private Key page, select Create a new private key and click Next 464 | * On the Configure Cryptography for CA, leave the default options and click Next 465 | * On the Configure CA Name page, enter a common name for the CA and click Next. This name can be the same as the server name, but it is usually changed to clearly identify the name as being a certificate authority. In this case, we will use “LAB1-W2K8R2-CA”. 466 | * On the Set Validity Period page, click Next 467 | * On the Configure Certificate Database page, click Next 468 | * On the Confirm Installation Selections page, click Install 469 | * Wait for the Installation Results page to appear, click Close and reboot if necessary to complete the installation process. 470 | 471 | Installing the WINS Server feature: 472 | 473 | * Launch the Server Manager 474 | * In the left pane, click Features 475 | * In the right pane, click Add Features to launch the Add Features wizard 476 | * In the Select Features page, select WINS Server and then click Next 477 | * In the Confirm Installation Selections page, click Install 478 | * Wait for the Installation Results page to appear, click Close and reboot if necessary to complete the installation process. 479 | 480 | ### Windows Server 2012 481 | 482 | Installing the Active Directory Domain Services Role: 483 | 484 | * Launch the Server Manager 485 | * At the top right, click Manage then click Add Roles and Features to launch the Add Roles and Features wizard 486 | * If the Before you begin page appears, click Next 487 | * On the Select installation type page, select Role-based or feature-based installation and click Next 488 | * On the Select destination server page, leave the Select a server from the server pool option selected, select the current server from the Server Pool list, and then click Next 489 | * On the Select server roles page, select Active Directory Domain Services. If prompted to add required features, click Add Features. Click Next to continue. 490 | * On the Select features page, click Next 491 | * On the Active Directory Domain Services page, click Next 492 | * On the Confirm installation selections page, click Install 493 | * Wait for the installation to complete and click Close 494 | 495 | Promoting the server to a domain controller: 496 | 497 | 498 | * Launch the Server Manager 499 | * On the top right, click Notifications (flag icon) and then click Promote this server to a domain controller. This option is only shown after the installation of the Active Directory Domain Services role, and is a post-deployment configuration task. The Active Directory Domain Services Configuration wizard will appear. 500 | * On the Deployment Configuration page, select Add a new forest and enter a FQDN for the domain in the Root domain name field such as “lab2.awake.local”. Click Next to continue. 501 | * On the Domain Controller Options page, select a Forest functional level and Domain functional level such as Windows Server 2008 R2. Ensure that the functional level you choose is compatible with the rest of your planned infrastructure. Leave the Domain Name System (DNS) server option selected. Enter a password in the Password and Confirm password fields, and then click Next. 502 | * On the DNS Options page, there should be a warning saying that a delegation for the DNS server cannot be created. This warning can be safely ignored. Click Next to continue. 503 | * On the Additional Options page, the NetBIOS domain name will be shown for verification. For instance, the corresponding NetBIOS name for the FQDN “lab2.awake.local” will be “LAB2”. Click Next to continue. 504 | * On the Paths page, click Next. 505 | * On the Review Options page, click Next 506 | * On the Prerequisites Check page, click Install 507 | * Wait for the installation to complete. The server will restart automatically. 508 | 509 | ## Client Configuration 510 | 511 | ### Windows 7 and Windows Server 2008 512 | 513 | Joining and existing domain: 514 | 515 | * Right-click Computer and then click Properties 516 | * Under Computer name, domain and workgroup settings click Change settings. The System Properties dialog will appear. 517 | + In the Computer Name tab, click Change. The Computer Name/Domain Changes will appear. 518 | + Under Member Of, select Domain, enter the domain name to join (“lab1.awake.local”) and click OK 519 | + A password prompt will appear. Authenticate using an account with permission to join the domain, and click OK. A message box welcoming you to the domain should appear, click OK. Another message box will inform you that you must restart the computer, click OK again. 520 | + A dialog will then ask you to restart the computer now or later. In both cases, you need to restart the computer before going further. 521 | 522 | ### Windows 8 and Windows Server 2012 523 | 524 | Joining and existing domain: 525 | 526 | * Open the System control panel page by pressing WinKey+X and clicking System in the menu that appears on the bottom left of the screen 527 | * Under Computer name, domain and workgroup settings click Change settings. The System Properties dialog will appear. 528 | + In the Computer Name tab, click Change. The Computer Name/Domain Changes will appear. 529 | * Under Member Of, select Domain, enter the domain name to join (“lab2.awake.local”) and click OK 530 | * A password prompt will appear. Authenticate using an account with permission to join the domain, and click OK. A message box welcoming you to the domain should appear, click OK. Another message box will inform you that you must restart the computer, click OK again. 531 | * A dialog will then ask you to restart the computer now or later. In both cases, you need to restart the computer before going further. 532 | 533 | # Remote Desktop Connection Broker 534 | 535 | ## Server Configuration 536 | 537 | ### Windows Server 2008 538 | 539 | * Launch the Server Manager 540 | * In the left pane, expand Roles, right-click Remote Desktop services and then click Add Role Services. The Add Role Services wizard will appear. 541 | * On the Select Role Services page, select Remote Desktop Connection Broker and click Next 542 | * On the Confirm Installation Selections page, click Install. Wait for the installation to complete and then click Close. 543 | 544 | # Remote Desktop Web Access 545 | 546 | ## Server Configuration 547 | 548 | ### Windows Server 2008 549 | 550 | * Launch the Server Manager 551 | * In the left pane, expand Roles, right-click Remote Desktop services and then click Add Role Services. The Add Role Services wizard will appear. 552 | * On the Select Role Services page, select Remote Desktop Web Access and click Next. You may be asked to install additional required services such as Web Server (IIS). 553 | * On the Introduction to Web Server (IIS) page, click Next 554 | * On the Select Role Services page, click Next 555 | * On the Confirm Installation Selections page, click Install. Wait for the installation to complete and then click Close. 556 | 557 | # Terminal Server Gateway 558 | 559 | ## Server Configuration 560 | 561 | ### Windows Server 2008 562 | 563 | * Launch the Server Manager 564 | * In the left pane, click Roles 565 | * In the right pane, click Add Roles to launch the Add Roles wizard 566 | * If the Before you begin page appears, click Next 567 | * On the Server Roles page, select Remote Desktop Services and click Next 568 | * On the Introduction to Remote Desktop Services page, click Next 569 | * On the Select Role Services page, select Remote Desktop Session Host and Remote Desktop Gateway and then click Next 570 | * On the Uninstall and Reinstall Applications for Compatibility page, click Next 571 | * On the Specify Authentication Method for Remote Desktop Session Host, select either Require Network Level Authentication or Do not require Network Level Authentication and click Next 572 | * On the Specify Licensing Mode page, select Configure later if you haven’t installed licenses yet, otherwise select the appropriate mode between Per Device and Per User and click Next 573 | * On the Select User Groups Allowed Access To This RD Session Host Server page, add the necessary user groups and click Next. Users from the Administrators group are allowed by default to connect using RDP. 574 | * On the Configure Client Experience page, select the features to enable such as Audio and video playback, Audio recording redirection and Desktop composition and click Next. For testing purposes, enabling all features is a good idea. 575 | * On the Choose and Server Authentication Certificate for SSL Encryption page, either choose an existing certificate or select Create a self-signed certificate for SSL encryption and click Next. The SSL certificate for the Terminal Server Gateway is different from the SSL certificate used by the RDP server and can be changed later. 576 | * On the Create Authorization Policies for RD Gateway page, select Now and click Next. The RD Gateway uses these policies to restrict both the users allowed to connect and the internal network resources that can be accessed. 577 | * On the Select User Groups That Can Connect Through RD Gateway page, add necessary user groups and click Next 578 | * In the Create an RD CAP for RD Gateway page, enter a name and select allowed authentication methods between Password and Smart card and click Next 579 | * In the Create an RD RAP for RD Gateway page, enter a name and select Allow users to connect to any computer on the network and click Next. Alternatively, select Allow users to connect only to computers in the following group to restrict access to a limited set of computers in the internal network. 580 | * On the Introduction to Network Policy and Access Services page, click Next 581 | * On the Select Role Services page, leave Network Policy Server selected and click Next 582 | * On the Introduction to Web Server (IIS) page, click Next 583 | * On the Select Role Services page, leave default options selected and click Next 584 | * On the Confirm Installation Selections page, click Install 585 | * Wait for the Installation Results page to appear, click Close and reboot if necessary to complete the installation process. 586 | 587 | ## Client Configuration 588 | 589 | ### Windows 7 590 | 591 | Ensure that both the client and the RD Gateway are on the same network, and that the client can connect to the server using its hostname, not its IP address. In this case, the server is called WIN20008R2SP1. The Administrator account is used for both authentication against the gateway and the remote desktop session host. 592 | 593 | Configuring Remote Desktop Connection for RD Gateway connection: 594 | 595 | * Launch Remote Desktop Connection (mstsc.exe) 596 | * Enter WIN2008R2SP1 in the Computer field, and Administrator in the User name field 597 | * Click Options at the bottom left of the Remote Desktop Connection window to expand advanced options 598 | * In the Advanced tab, click Settings in the Connect from anywhere section. The RD Gateway Server Settings dialog will appear 599 | + Under Connection Settings, select Use these RD Gateway server settings. In the Server name field, enter WIN2008R2SP1 and select Ask for password (NTLM) as the Logon method. Unselect the Bypass RD Gateway server for local addresses option to ensure usage of the RD Gateway in a test environment. 600 | + Under Logon settings, select Use my RD Gateway credentials for the remote computer 601 | + Click OK to return to Remote Desktop Connection 602 | * Click Connect 603 | * In the Windows Security dialog, enter your credentials for the Administrator account. This dialog should say that the credentials will be used for a list of two computers, where one of them is listed as being an RD Gateway server. 604 | * If you are using a self-signed certificate or an untrusted certificate, which is most likely the case in a test environment, a Remote Desktop Connection warning dialog will inform you that the identity of the RD Gateway cannot be verified. Do not click OK, since it will abort the connection sequence. The certificate needs to be saved and imported in the proper certificate store before we can successfully connect. Open the Certificate dialog by clicking View Certificate. 605 | + In the Details tab, click Copy to File to open the Certificate Export Wizard 606 | - In the Welcome to the Certificate Export Wizard page, click Next 607 | - In the Export File Format page, select DER encoded binary X.509 (CER) and click Next 608 | - In the File to Export page, specify a destination file name and path, such as gateway.cer in the Documents folder and click Next 609 | - In the Completing the Certificate Export Wizard page, click Finish to close the wizard 610 | + Close the Certificate dialog by clicking OK 611 | * Close the Remote Desktop Connection warning dialog by clicking OK. The connection sequence will be aborted, but the RD Gateway certificate has been saved first. The certificate can now be imported in the Trusted Root Certification Authorities store for the client to accept identify the server on the next connection. 612 | 613 | Installing RD Gateway certificate for trust: 614 | 615 | * Double-click the RD Gateway certificate (gateway.cer in Documents from the previous steps). The Certificate dialog will appear. 616 | * In the General tab, click Install Certificate. The Certificate Import wizard will appear. 617 | + In the Welcome to the Certificate Import Wizard page, click Next 618 | + In the Certificate Store page, select Place all certificates in the following store. Click Browse to open the Select Certificate Store dialog 619 | - Select Trusted Root Certification Authorities and click OK 620 | + Click Next, and then Finish in the Completing the Certificate Import Wizard page. A Security Warning dialog will appear asking to confirm the installation of the certificate, click Yes and then OK. 621 | + Click OK to close the Certificate dialog 622 | -------------------------------------------------------------------------------- /Configuration/FreeRDP-Configuration-Manual.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/Configuration/FreeRDP-Configuration-Manual.pdf -------------------------------------------------------------------------------- /Developer/FreeRDP-Developer-Manual.markdown: -------------------------------------------------------------------------------- 1 | % FreeRDP Developer Manual 2 | % Marc-André Moreau 3 | % Awake Coding Consulting Inc. 4 | 5 | # Introduction 6 | 7 | ## Glossary 8 | 9 | To be expanded. 10 | 11 | ## References 12 | 13 | [FreeRDP User Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/User/FreeRDP-User-Manual.pdf?raw=true "FreeRDP User Manual") 14 | 15 | [FreeRDP Configuration Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Configuration/FreeRDP-Configuration-Manual.pdf?raw=true "FreeRDP Configuration Manual") 16 | 17 | [FreeRDP Testing Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Testing/FreeRDP-Testing-Manual.pdf?raw=true "FreeRDP Testing Manual") 18 | 19 | ## Getting Started 20 | 21 | ### Linux 22 | 23 | #### Debian / Ubuntu / Mint 24 | 25 | FreeRDP: 26 | 27 | sudo apt-get install \ 28 | build-essential git-core cmake \ 29 | libssl-dev \ 30 | libx11-dev libxext-dev libxinerama-dev libxcursor-dev libxkbfile-dev \ 31 | libxv-dev libxi-dev libxdamage-dev libxrender-dev libxrandr-dev \ 32 | libasound2-dev libcups2-dev libpulse-dev \ 33 | libavutil-dev libavcodec-dev \ 34 | libgstreamer0.10-dev libgstreamer-plugins-base0.10-dev 35 | 36 | FreeRDS: 37 | 38 | sudo apt-get install \ 39 | libpciaccess-dev libpam0g-dev libpng12-dev libjpeg-dev intltool libexpat1-dev libxml-libxml-perl \ 40 | libtool bison flex xsltproc libfreetype6-dev libfontconfig1-dev libpixman-1-dev xutils-dev x11proto-gl-dev mesa-common-dev xorg-dev libprotobuf-c0-dev protobuf-c-compiler libboost-dev 41 | 42 | #### (Open)SUSE 43 | 44 | 45 | FreeRDP: 46 | 47 | sudo zypper install \ 48 | gcc git cmake \ 49 | libopenssl-devel \ 50 | libX11-devel libXext-devel libXinerama-devel libXcursor-devel libxkbfile-devel \ 51 | libXv-devel libXi-devel libXdamage-devel libXrender-devel libXrandr-devel \ 52 | libpulse-devel alsa-devel cups-devel \ 53 | ffmpeg-devel libavutil-devel \ 54 | gstreamer-0_10-devel gstreamer-0_10-plugins-base-devel 55 | 56 | ffmpeg and gstreamer development libraries are available in the [Restricted Formats](http://opensuse-community.org/Restricted_formats "Restricted Formats") community repository. 57 | 58 | FreeRDS: 59 | 60 | sudo zypper install \ 61 | autoconf automake libtool bison flex libxslt-tools gcc-c++ llvm \ 62 | libpciaccess-devel pam-devel libpng-devel libjpeg-devel intltool libexpat-devel \ 63 | libpixman-1-0-devel perl-libxml-perl freetype2-devel fontconfig-devel \ 64 | protobuf-c protobuf-devel boost-devel 65 | 66 | #### CentOS / REHL / Fedora 67 | 68 | FreeRDP: 69 | 70 | sudo yum install \ 71 | openssl-devel \ 72 | libX11-devel libXext-devel libXinerama-devel libXcursor-devel libxkbfile-devel \ 73 | libXv-devel libXtst-devel libXi-devel libXdamage-devel libXrandr-devel \ 74 | alsa-lib-devel cups-devel ffmpeg-devel 75 | 76 | The version of cmake available in the CentOS repositories is too old, use a more recent version: 77 | 78 | wget http://pkgs.repoforge.org/cmake/cmake-2.8.8-1.el6.rfx.x86_64.rpm 79 | sudo rpm -i cmake-2.8.8-1.el6.rfx.x86_64.rpm 80 | 81 | FreeRDS: 82 | 83 | sudo yum install \ 84 | finger patch gcc gcc-c++ make autoconf libtool automake pkgconfig \ 85 | openssl-devel gettext file pam-devel libX11-devel libXfixes-devel libjpeg-devel \ 86 | flex bison libxslt perl-libxml-perl xorg-x11-font-utils xmlto-tex docbook-utils-pdf 87 | 88 | # Build Environment 89 | 90 | ## CMake Build System 91 | 92 | FreeRDP uses CMake as its build system. CMake is not an ordinary build system: it generates project files for other build systems to use. This means that we have only one set of scripts to maintain while having the flexibility of using any of the build systems supported by CMake. For instance, FreeRDP developers can use Visual Studio, Xcode, Eclipse, or just plain regular makefiles without having to separately maintain project files for the development tools they are using. 93 | 94 | ### Installation 95 | 96 | FreeRDP requires CMake 2.8, but it is highly recommended to use the very latest builds available from the CMake website (www.cmake.org). This is because certain useful features are available only in certain versions that we cannot require since they are too recent. Using an older version of CMake 2.8 will work, but some features taking advantage of functionality present in more recent CMake releases may be disabled. For instance, FreeRDP offers a monolithic build option that combines all libraries into a single one using functionality found in CMake 2.8.9. If you are using CMake 2.8.8, this option will be disabled. 97 | 98 | Recent CMake builds are available from the CMake download page: 99 | 100 | [http://www.cmake.org/cmake/resources/software.html](http://www.cmake.org/cmake/resources/software.html) 101 | 102 | #### Linux 103 | 104 | CMake is packaged by most Linux distributions and should be easy to install. However, since FreeRDP leverages some of the newest CMake features, it is very likely that the version packaged for your system is not the latest one. In this case, simply download the CMake Linux build from the CMake website and install it manually to the appropriate location. 105 | 106 | #### Mac OS X 107 | 108 | The easiest way to install CMake on Mac OS X is by using the latest build available on the CMake website. Alternatively, one can use common Mac OS X package manager such as homebrew to install CMake. 109 | 110 | #### Windows 111 | 112 | Installing CMake on Windows is fairly straightforward. Download either the installer of the zip version of the Windows build from the CMake website. Using the installer is simpler, but you might want to consider choosing the zip archive if you need to work from a machine where you do not have sufficient rights to run an installer. 113 | 114 | ## Git Version Control 115 | 116 | FreeRDP is hosted on GitHub, and uses git for version control. Git is one of those tools that is extremely powerful but a bit hard to grasp at first. Luckily, a lot of the complexity of git is made much simpler through the GitHub collaborative coding interface, and provides us with a functional workflow for accepting contributions with minimal overhead. 117 | 118 | If you are new to FreeRDP and don’t want to bother learning the git basics for now, feel free to simply download a source tarball from GitHub and move on to the next step. However, you will eventually have to learn it, especially if you want to synchronize your work with the latest sources, or contribute your changes back to the community. If you are not so sure about how to contribute changes which have not been done cleanly with git, ping one of the developers in the IRC channel. It’s never fun to get contributions in the form of tarball in an email, but we’ll take it anyway. Please understand, however, that since this require much more effort on our side, clean integration of the changes will only happen when time allows for it. 119 | 120 | ### Installation 121 | 122 | Git is packaged for most Linux distributions and should be easily obtained. Otherwise, and for all other platforms, pre-built packages are available from the Git download page (http://git-scm.com/downloads) 123 | 124 | Many other third-party Git packages exist for various operating systems. On Windows, git can be installed in Cygwin [http://www.cygwin.com/](http://www.cygwin.com/), or through msysgit [http://msysgit.github.com/](http://msysgit.github.com/) 125 | 126 | ### Configuration 127 | 128 | Configuring Git can be tricky, especially for the part where one has to generate SSH keys to be used for authentication with GitHub instead of passwords. 129 | 130 | One does not necessarily need to use GitHub, but unless you know what you are doing you should simply create a GitHub account and follow the regular GitHub workflow. 131 | 132 | GitHub offers extensive help which everyone should refer to: https://help.github.com/ 133 | 134 | Alternatively, the Pro Git book is available for free online: http://git-scm.com/book 135 | 136 | The Git Reference is concise, small and to the point: http://gitref.org/ 137 | 138 | Along with the GitHub help, there is an excellent step-by-step introduction to GitHub on the GitHub Learn website: http://learn.github.com/p/setup.html 139 | 140 | If you need more assistance getting started, please come on IRC and we’ll help you. 141 | 142 | ## Native Compilation 143 | 144 | ### Linux 145 | 146 | In debian-based distributions, the build-essential package installs GCC and common development tools necessary for C/C++ development. 147 | 148 | ### Mac OS X 149 | 150 | Xcode is the easiest way develop for Mac OS X, and is distributed for free on the Mac App Store. 151 | 152 | The Xcode command line tools are not installed by default with Xcode and are necessary: 153 | 154 | * On the Xcode menu, click Xcode and then Preferences 155 | * Select the Downloads tab from the Preferences panel 156 | * Select the Components sub-tab from the Downloads tab 157 | * Select Command line tools and click install on the right 158 | 159 | #### SDKs 160 | 161 | Whenever Xcode is updated through the Mac App Store, it tends to remove SDKs for older versions of Mac OS X to only keep the new ones. In order to provide better backwards compatibility, one can download older releases of Xcode and manually install the missing SDKs in newer versions of Xcode. This process has to be repeated whenever Xcode is updated. 162 | 163 | * Download the last release of Xcode containing the SDK you want and mount it. 164 | * Right-click the Xcode package, select "Show Package Contents". 165 | * Browse to Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs. 166 | * Save a copy of the desired SDK like "MacOSX10.6.sdk" for later. 167 | * Install Mac OS X SDKs to /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs. 168 | 169 | Mac OS X 10.6 Snow Leopard SDK: Xcode 4.3.3 170 | 171 | Mac OS X 10.7 Lion SDK: Xcode 4.6.3 172 | 173 | ### Windows 174 | 175 | FreeRDP supports all versions of Windows starting from Windows XP all the way up to Windows 8. Windows development is normally done using Visual Studio 2010 or Visual Studio 2012. If you do not own a license of Visual Studio, the Express edition is available for free and should work fine. 176 | 177 | To build FreeRDP on Windows, you will first need to install OpenSSL (see the “Prerequisites” section), along with the rest of the Windows build environment, including CMake. When installing CMake, it is recommended to select the option that adds it to the system path. 178 | 179 | Refer to the “Build Configuration” section to learn the basic usage of CMake. For Windows, common CMake generators are “Visual Studio 2010” and “Visual Studio 2012”. There is also the “NMake Makefiles” generator which may be suitable for more advanced Windows developers who would prefer a build system that does not require the full Visual Studio IDE. 180 | 181 | ## Cross-Compilation 182 | 183 | ### Android 184 | 185 | Android development can be done from Linux, Mac OS X and Windows. There are two development kits for Android: the Software Development Kit (SDK) and the Native Development Kit (NDK). The SDK is for Java, while the NDK is for C/C++. Since it is not possible to write completely native Android applications (at least not under normal circumstances), we will need both the Android SDK and NDK for FreeRDP development. The NDK alone is enough to build the FreeRDP libraries, but not enough to build a complete application. 186 | 187 | #### Java Development Kit 188 | 189 | Before installing the SDK, you will need to install the Java Development Kit. On Windows, the Sun/Oracle JDK is easy to download and install. On Linux, OpenJDK is easier to install from your distribution’s package manager. 190 | 191 | #### Android SDK and NDK 192 | 193 | Download the Android SDK and Android NDK from the Android developer website: 194 | 195 | http://developer.android.com/tools/ 196 | 197 | Extract or install the SDK and NDK to a path which is easy to locate. The Windows installer installs the SDK into “%PROGRAMFILES(x86)%/Android” by default. On Linux, using /opt/android-sdk and /opt/android-ndk is common practice. Regardless of where you choose to install the SDK and NDK, you will need to configure the ANDROID_SDK and ANDROID_NDK environment variables to point to them. It is also very convenient to add $ANDROID_SDK/tools and $ANDROID_SDK/platform-tools to your system path in order to have the Android utilities available without specifying the full path. 198 | 199 | Once both the SDK and NDK are installed, the first thing to do (it takes some time) is to launch the “android” utility found in $ANDROID_SDK/tools. On Windows, the same utility can be launched with the “SDK Manager” found in %ANDROID_SDK%. In the SDK manager, select target Android platforms of interest, such as Android 2.3.3 (API 10) or Android 4.0 (API 14), click install, accept the licenses, and be patient because it takes time to download and install everything. The good news is that you can leave the SDK manager open while moving on to setting up the NDK. 200 | 201 | #### Environment Variables 202 | 203 | You will need to set a certain number of environment variables to ease Android development. On Linux, this can be done by editing the .bashrc file, and on Mac OS X, this can be done by editing the .profile file. 204 | 205 | export NDK=/opt/android-ndk 206 | export ANDROID_NDK=$NDK 207 | export ANDROID_SDK=/opt/android-sdk 208 | export PATH=$ANDROID_SDK/tools:$ANDROID_SDK/platform-tools:$PATH 209 | 210 | #### Preparing Toolchain 211 | 212 | The prebuilt toolchains that come with the Android NDK should suffice, but if you need to build your own, invoke the make-standalone-toolchain.sh script: 213 | 214 | $NDK/build/tools/make-standalone-toolchain.sh --platform=android-9 --install-dir=$ANDROID_STANDALONE_TOOLCHAIN 215 | 216 | Where $ANDROID_STANDALONE_TOOLCHAIN is the location where you want to install your standalone toolchain. 217 | 218 | #### Invoking CMake 219 | 220 | When invoking CMake, the path to the Android CMake toolchain needs to be passed: 221 | 222 | cmake -DCMAKE_TOOLCHAIN_FILE=cmake/AndroidToolchain.cmake . 223 | 224 | The Android CMake toolchain will make use of the environment variables defined in the previous section, so make sure they are correct before invoking CMake. 225 | 226 | The Android CMake toolchain included with FreeRDP is based on the android-cmake project: 227 | 228 | https://code.google.com/p/android-cmake/ 229 | 230 | #### Android Project 231 | 232 | While the native portion of the FreeRDP Android port is built using CMake, the Android Java code is built using ant or Eclipse with the ADT plugin. The Android project structure is explained here: 233 | 234 | http://developer.android.com/tools/projects/ 235 | 236 | This project is generated and maintained using the android command-line tool: 237 | 238 | http://developer.android.com/tools/projects/projects-cmdline.html 239 | 240 | The root of the Android project tree is located in client/Android: 241 | 242 | src: android Java code (built with ant or Eclipse) 243 | 244 | bin: build output directory (.apk files) 245 | 246 | jni: android native code (built with cmake) 247 | 248 | gen: android generated code such as R.java 249 | 250 | assets: project assets, added as-is to the .apk 251 | 252 | res: contains XML configuration files for menus, layouts, strings, etc 253 | 254 | libs: contains third-party libraries for both Java and native code 255 | 256 | In order to verify that libfreerdp-android.so gets properly packaged in the .apk, simply unzip the resulting .apk files to see its contents (an .apk file is a regular zip file with a different extension). 257 | 258 | #### Ant Building 259 | 260 | Inside client/Android, invoke ant help to list targets: 261 | 262 | ant help 263 | 264 | Targets of interest are debug and release, which generate a debug or release .apk file in the bin directory: 265 | 266 | ant debug 267 | ant release 268 | 269 | The resulting .apk files can be deployed to actual devices or the Android emulator. 270 | 271 | #### Eclipse Building 272 | 273 | There is an Eclipse project located in client/Android, which is different from any potential Eclipse project generated by CMake in the root of the FreeRDP source tree. It can be imported in Eclipse like any other regular Eclipse project. Make sure to configure the Eclipse ADT plugin properly beforehand. 274 | 275 | ### iOS 276 | 277 | iOS development requires Xcode and the same development environment as for Mac OS X with the addition of the iOS SDK. Certain features like deploying to real devices are limited to Apple developers only. 278 | 279 | #### iOS SDKs 280 | 281 | Just like for Mac OS X SDKs, older versions of the iOS SDKs disappear when you update to a newer version of Xcode. 282 | 283 | * Download the last release of Xcode containing the SDK you want and mount it. 284 | * Right-click the Xcode package, select "Show Package Contents". 285 | * Browse to Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs. 286 | * Save a copy of the desired SDK like "iPhoneOS6.1.sdk" for later. 287 | * Install iOS SDKs to /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs. 288 | 289 | iOS 6.1 SDK: Xcode 4.6.3 290 | 291 | #### Invoking CMake 292 | 293 | FreeRDP includes a modified version of the ios-cmake toolchain in the cmake directory. The original toolchain can be found here: 294 | 295 | http://code.google.com/p/ios-cmake/ 296 | 297 | When invoking CMake for iOS development, the iOS toolchain needs to be passed like this: 298 | 299 | cmake -DCMAKE_TOOLCHAIN_FILE=cmake/iOSToolchain.cmake . 300 | 301 | ## Prerequisites 302 | 303 | The general approach towards prerequisites is simple: avoid hard dependencies as much as possible, make soft dependencies modular and optional. This may appear a bit extreme, but it is not when FreeRDP needs to run on a very large variety of platforms with a small footprint. Convenience always comes at a cost, and we have learned from out past mistakes that in our case the extra effort is worth it. 304 | 305 | ### OpenSSL 306 | 307 | FreeRDP’s only strong dependency is OpenSSL. All other dependencies can be made optional with the side effect of disabling the modules that depend on it. It is within our plans to make FreeRDP less dependent on OpenSSL in the future through the WinPR project: instead of using OpenSSL directly, we will implement the equivalent portions of what we need from the Windows API. The WinPR implementation of the Windows API will make use of OpenSSL and eventually add support for other cryptographic libraries. Not only will this enable OpenSSL-free builds of FreeRDP on Windows, but it will also give us an abstraction layer over OpenSSL, allowing us to add support for alternative libraries such as NSS, PolarSSL and CyaSSL. 308 | 309 | OpenSSL is used for TLS, MD4, MD5, HMAC-MD5, SHA1, HMAC-SHA1, RSA, DES3, Base64, BigNum arithmetic and certificate validation. RDP8 support will require DTLS which is also provided by OpenSSL. 310 | 311 | #### Linux 312 | 313 | OpenSSL is packaged by most Linux distributions, and is easy to compile from source. 314 | 315 | #### Mac OS X 316 | 317 | OpenSSL used to ship with Mac OS X until Mac OS X 10.8 (Mountain Lion). Luckily, OpenSSL ships with Xcode. Otherwise, OpenSSL can be obtained from common Mac OS X package managers such as macports. 318 | 319 | Command-line tools are not installed by default with Xcode and are necessary. 320 | 321 | #### Windows 322 | 323 | A binary distribution of OpenSSL is maintained by “The Shining Light Productions”: 324 | 325 | http://slproweb.com/products/Win32OpenSSL.html 326 | 327 | In order to use it, download both the Win32 OpenSSL installer (the full one, not the light) and the Visual C++ 2008 Redistributables. Install the Visual C++ redistributables first, since OpenSSL requires it. Install OpenSSL in the default path suggested by the installer (C:\\OpenSSL-Win32), otherwise may not find it automatically. If you install OpenSSL in a path not found by CMake, you will need to use the OPENSSL_ROOT_DIR option to tell CMake where to find it. 328 | 329 | ##### Compilation 330 | 331 | The Visual C++ 2008 Redistributable requirement is a problem if you want to ship FreeRDP for Windows without an installer. Unfortunately, this requires building OpenSSL manually and modifying the default build scripts to link against the static Visual Studio runtime (/MT switch as opposed to the default /MD switch used by OpenSSL). There are many pitfalls along the way if you want to make a proper build of FreeRDP and OpenSSL using the static Visual Studio runtime. 332 | 333 | A modified version of OpenSSL for Windows is available for the sake of convenience here: 334 | 335 | https://github.com/awakecoding/openssl-win32 336 | 337 | The sources were deliberately put on git to allow others to consult the history of modifications from the vanilla sources that allow for an easier Windows build. 338 | 339 | In order to build OpenSSL, you will need to install the following prerequisites 340 | 341 | ActivePerl (http://www.activestate.com/activeperl) 342 | NASM for Windows (http://www.nasm.us/) 343 | Microsoft Visual Studio (2010 or 2012) 344 | Raspberry Perl can be used instead of ActivePerl, and other versions of Visual Studio can be used, but the build scripts provided will need to be modified accordingly. 345 | 346 | Once prerequisites are installed, download the modified OpenSSL sources from the openssl-win32 GitHub repository. In the root of the openssl-win32 directory, you should find two batch files: win32_env.bat and win32_build.bat. Edit both of them to ensure that the path variables they use are correct for your environment. 347 | 348 | Once the batch files are properly edited, open a command prompt and move to the root of the openssl-win32 directory. Run win32_env.bat once in order to configure environment variables. Run win32_build.bat in order to build OpenSSL. When building is complete, you should find the resulting build in the “build” directory. This directory can be renamed to OpenSSL-Win32 and moved to C:\\OpenSSL-Win32 to be automatically picked up by CMake. Beware, however, that this build has only been tested at this point with FreeRDP release builds configured with the MSVC_RUNTIME=”static” option. 349 | 350 | If your FreeRDP builds start crashing for no obvious reason when freeing memory, this is most likely the side effect of an MSVC runtime mismatch. Don’t waste your time trying to find problems where they are not: even if you think you’ve compiled everything correctly chances are that you’re fighting with the pickiness of OpenSSL builds on Windows. 351 | 352 | #### Android 353 | 354 | Even though OpenSSL is used in Android, the headers and libraries are not part the Android NDK. This means that in order to compile FreeRDP for Android, one must first compile OpenSSL manually. 355 | 356 | Android uses its own build system which is not supported by OpenSSL out of the box. A modified version of OpenSSL with Android build scripts is available through the Android Open Source Project (AOSP). This is the library which is used for the Android operating system itself, but not made available to application developers through the NDK. 357 | 358 | This may look like a good deal, but further modifications to default OpenSSL Android port are required before it can be built for usage with FreeRDP, such as adding an option for a static build. 359 | 360 | Usable OpenSSL sources are available from “The Guardian Project”: 361 | https://github.com/guardianproject/android-external-openssl-ndk-static 362 | 363 | Further modifications to the OpenSSL sources have been made by the FreeRDP developers and can be found here: 364 | 365 | git://github.com/bmiklautz/android-external-openssl-ndk-static.git 366 | git://github.com/awakecoding/android-external-openssl-ndk-static.git 367 | 368 | Clone the OpenSSL git repository in external/openssl in the root of the FreeRDP source tree: 369 | 370 | cd external 371 | git clone git://github.com/awakecoding/android-external-openssl-ndk-static.git openssl 372 | 373 | Ensure you have the proper environment variables configured for Android development as covered earlier. Move to the root of the OpenSSL source tree use the following command to build: 374 | 375 | $NDK/ndk-build 376 | 377 | You can optionally install OpenSSL globally by copying the headers and library files to your target android platform directory: 378 | 379 | export ANDROID_PLATFORM=android-9 380 | cp -R include/ $NDK/platforms/$ANDROID_PLATFORM/arch-arm/usr/include/ 381 | cp obj/local/armeabi/*.a $NDK/platforms/$ANDROID_PLATFORM/arch-arm/usr/lib/ 382 | 383 | If OpenSSL is not installed globally, you will need to manually specify its path when invoking cmake with FREERDP_ANDROID_EXTERNAL_SSL_PATH. 384 | 385 | cmake -DCMAKE_TOOLCHAIN_FILE=cmake/AndroidToolchain.cmake -DANDROID_NDK=/opt/android-ndk -DANDROID_SDK=/opt/android-sdk -DFREERDP_ANDROID_EXTERNAL_SSL_PATH=external/openssl . 386 | 387 | If ANDROID_SDK and ANDROID_NDK are set as environment variables, they will be used by cmake, reducing the size of the command. If openssl is present in external/openssl, it will be used automatically by cmake: 388 | 389 | export ANDROID_SDK=/opt/android-sdk 390 | export ANDROID_NDK=/opt/android-ndk 391 | cmake -DCMAKE_TOOLCHAIN_FILE=cmake/AndroidToolchain.cmake . 392 | 393 | #### iOS 394 | 395 | There is no pre-built OpenSSL iOS package, so again we have to build our own. The “iOSPorts” collection of iOS ports simplifies the task of building OpenSSL for iOS. 396 | 397 | Download the iOSPorts collection from: https://github.com/bindle/iOSPorts 398 | 399 | Launch Terminal and move to the root of the iOSPorts source tree. From there, type the following commands: 400 | 401 | cd ports/security/openssl/ 402 | make 403 | cd openssl 404 | ../build-aux/configure-wrapper.sh 405 | make install 406 | 407 | This will download, patch, configure build and install OpenSSL for iOS. The default installation path is in /tmp/iOSPorts. The important files are the include and lib directories from the OpenSSL, which we will need to copy to a location inside the iOS SDK. 408 | 409 | The system root for the iOS SDK can be found in the following path: 410 | 411 | /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS7.0.sdk/ 412 | 413 | Where “iPhoneOS7.0.sdk” is subject to change depending on the SDK version. 414 | 415 | To ease installation, configure the following environment variables: 416 | 417 | export IOS_SDK_ROOT=/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS7.0.sdk 418 | 419 | export OPENSSL_ROOT=/tmp/iOSPorts 420 | 421 | Then enter the following commands to install OpenSSL in the iOS SDK: 422 | 423 | sudo cp -R "$OPENSSL_ROOT/include" "$IOS_SDK_ROOT/usr" 424 | sudo cp "$OPENSSL_ROOT/lib/libssl.a" "$IOS_SDK_ROOT/usr/lib/libssl.a" 425 | sudo cp "$OPENSSL_ROOT/lib/libcrypto.a" "$IOS_SDK_ROOT/usr/lib/libcrypto.a" 426 | 427 | This procedure only has to be executed once per iOS SDK. After this, OpenSSL should be picked up automatically by CMake. 428 | 429 | ### X11 430 | 431 | #### Linux 432 | 433 | For the X11 client, you will need: 434 | 435 | sudo apt-get install libx11-dev libxcursor-dev libxkbfile-dev libxinerama-dev 436 | 437 | Additionally, for the X11 server, you will need: 438 | 439 | sudo apt-get install libxext-dev libxtst-dev libxdamage-dev 440 | 441 | #### Mac OS X 442 | 443 | If the X11 SDK used to ship with XCode, it was removed from its newer versions. In order to get the X11 dependencies satisfied, one has to obtain it from the XQuartz open source project: 444 | 445 | http://xquartz.macosforge.org/ 446 | 447 | #### Windows 448 | 449 | Even if a native Windows port is available, it is possible to compile the X11 FreeRDP client on Windows using Cygwin. Please note, however, that this particular configuration is rarely tested. 450 | 451 | # Build Configuration 452 | 453 | Projects like FreeRDP need to conform to a large number of requirements at the same time while remaining highly flexible, portable, fast, small, modular, reusable, testable, configurable, and the list goes on. It may not be obvious, but one of the challenges of open source development is having to please everybody at the same time. Different vendors want FreeRDP built in certain ways, with nice extension points for themselves to easily maintain their extensions separately, with just about any option that fits their needs within the upstream sources. It turns out that providing everybody with what they want is possible with enough CMake scripting. Nevertheless, the task of offering build configuration for all these needs makes build configuration management quite complex. 454 | 455 | ## CMake 456 | 457 | Prior to generating build scripts for your environment, you should ensure that you have CMake installed and available within your system path. Installing CMake is covered in the previous section of this manual. 458 | 459 | ### Introduction 460 | 461 | To generate build scripts, open a terminal, move to the root of the source tree, and type: 462 | 463 | cmake . 464 | 465 | This will tell CMake to generate build scripts using the CMake scripts found in the local directory (“.”). If the command fails, you might need to invoke CMake with additional options which we will cover in the following sections. The path to the directory where the root CMake script is contained is always the last argument of the cmake command. 466 | 467 | CMake looks for files with the name CMakeLists.txt. These files are the equivalent of makefiles, written in the CMake scripting language. A root CMakeLists.txt script can include other such scripts from subdirectories. 468 | 469 | ### Generators 470 | 471 | CMake scripts are used to generate platform-specific build scripts with the help of CMake generator. When no generator is specified, CMake attempts finding a suitable default. If it can’t find any, generation will fail. Most of the time, you will want to specify the generator of your choice using the –G “Generator Name” option. Here is a list of common generators: 472 | 473 | * Xcode 474 | * Unix Makefiles 475 | * NMake Makefiles 476 | * Visual Studio 11 477 | * Visual Studio 10 478 | * Visual Studio 9 2008 479 | * Eclipse CDT4 – Unix Makefiles 480 | * Eclipse CDT4 – NMake Makefiles 481 | 482 | In order to generate an Eclipse project on Linux, one would type: 483 | 484 | cmake –G “Eclipse CDT4 – Unix Makefiles” . 485 | 486 | For simple makefiles without an Eclipse project, “Unix Makefiles” would do it. 487 | 488 | On Windows, the generator would likely be “Visual Studio 10” (Visual Studio 2010) 489 | 490 | On Mac OS X, the "Xcode" generator would be appropriate. 491 | 492 | ### CMake Cache 493 | 494 | When CMake executes, it generates CMakeCache.txt, or the CMake cache. The cache stores values from previous executions. Whenever major changes happen, such as installing new dependencies, modifying the CMake scripts, or when something does not work as expected it is advised to simply delete the CMake cache and regenerate from scratch. Clearing the CMake cache is done by deleting the CMakeCache.txt file: 495 | 496 | rm CMakeCache.txt 497 | 498 | The CMake cache is a simple text file which looks like a simple configuration file with one option per line. You can modify it in a text editor, but it is preferable to use a specialized editor. On Linux, there is ccmake, which is ncurses-based (simple text-based GUI inside the terminal). On Windows, there is cmake-gui. These tools are very useful in order to visualize and edit the entire set of options available for the current project. 499 | 500 | ### Configuration Files 501 | 502 | If you have to frequently regenerate the CMake, the task of entering all the options that you want over and over again will be cumbersome. A flexible build system also means a large number of options, and the process of typing all of them every time is not only slow but also error prone. This is where storing build options in a configuration file becomes useful. 503 | 504 | Luckily for us, CMake supports using values from an initial cache when generating a new one. The format of the initial cache is the same as the CMakeCache.txt file. The easiest way to use the initial cache is to create a text file and the desired options from a previously generated cache. Since many values in the cache are specific to the current build environment, it is not recommend to copy the entire generated cache to be used as an initial cache. 505 | 506 | Here is an example: when developing, I like to keep a working version of FreeRDP installed in a directory separated from other less stable builds. Such a build comes in handy when I need to use FreeRDP rather than develop it, and my current development build is broken. For this build, I use the following options when invoking CMake: 507 | 508 | cmake –DCMAKE_INSTALL_PREFIX=”/opt/freerdp” –DCMAKE_BUILD_TYPE=Release –DSTATIC_CHANNELS=on –DMONOLITHIC_BUILD=on –DWITH_SERVER=on . 509 | 510 | In the resulting CMakeCache.txt file, the options I’ve passed will look like this: 511 | 512 | WITH_SERVER:BOOL=on 513 | 514 | STATIC_CHANNELS:BOOL=on 515 | 516 | MONOLITHIC_BUILD:BOOL=on 517 | 518 | CMAKE_BUILD_TYPE:STRING=Release 519 | 520 | CMAKE_INSTALL_PREFIX:STRING=/opt/freerdp 521 | 522 | You will notice that the format in the CMake cache is a bit different that the format used at the command-line. In reality, they turn out to be the same, except that CMake guesses the parameter type when you invoke it. Values like “on/off” are recognized as BOOL, but if you were to explicitly specify the STRING data type, CMake would consider “on/off” as a STRING rather than a BOOL. 523 | 524 | The above options can be copied in a text file which I will call “StableBuildCache.txt” for the sake of this example. The next time, instead of retyping everything, all that is needed is passing the initial cache to CMake using the –C option: 525 | 526 | cmake –C StableBuildCache.txt . 527 | 528 | This will have the same effect as passing all the desired parameters through the command-line, with much less effort. 529 | 530 | ### Out-of-Source Build 531 | 532 | One of the powerful features of CMake is the ability to make out-of-source builds. Normally, a build is made in-source, meaning that build scripts and build outputs are produced in the same directories as the sources. An out-of-source build, as the name says, produces build scripts and build outputs outside of the sources. 533 | 534 | To generate out-of-source build scripts, invoke CMake from a directory different from the source tree, while providing the path to the directory where the root CMake script is contained. For instance, if I have my sources in ~/src/FreeRDP, but I want to build everything inside the ~/build/FreeRDP directory, here is what the command would look like: 535 | 536 | cmake ../../src/FreeRDP 537 | 538 | Where the current working directory is ~/build/FreeRDP. 539 | 540 | ## Options 541 | 542 | CMake options are passed to the cmake command, prefixed with –D (D for Define). BOOL options are either ON or OFF. STRING options are just regular strings, and can be put between quotes. 543 | 544 | ### CMake Options 545 | 546 | CMAKE_BUILD_TYPE (STRING [Release]): Defines the build type, usually Debug or Release. 547 | 548 | BUILD_SHARED_LIBS (BOOL [OFF]): Build libraries with an unspecified build type as shared libraries. This option is turned on by default in FreeRDP. 549 | 550 | CMAKE_INSTALL_PREFIX (STRING): Path prefix for installation. On Linux, this is /usr/local by default. 551 | 552 | ### Build Options 553 | 554 | MONOLITHIC_BUILD (BOOL [OFF]): Combine smaller libraries into single, larger, monolithic libraries. In monolithic build mode, there is a single libfreerdp instead of multiple libraries such as libfreerdp-core, libfreerdp-cache, libfreerdp-utils, etc. 555 | 556 | STATIC_CHANNELS (BOOL [ON]): Build all channels statically, including channels normally built as plugins. Client static channels are bundled in libfreerdp-client, and server static channels are bundled in libfreerdp-server. 557 | 558 | BUILD_TESTING (BOOL [OFF]): Enable CTest and build unit tests. Unit tests are located in “test” subdirectories, and can be executed with the ctest command. 559 | 560 | BUILD_SAMPLE (BOOL [OFF]): Build sample code, such as sample channels, clients or servers. 561 | 562 | ### Mac OS X Options 563 | 564 | Mac OS X has specific options for 32-bit, 64-bit and universal binaries. By default, cmake will only build for the native architecture. Target architectures can be specified with the CMAKE_OSX_ARCHITECTURES option: 565 | 566 | cmake -DCMAKE_OSX_ARCHITECTURES="i386" -G Xcode . 567 | cmake -DCMAKE_OSX_ARCHITECTURES="x86_64" -G Xcode . 568 | cmake -DCMAKE_OSX_ARCHITECTURES="i386;x86_64" -G Xcode . 569 | 570 | Where i386 is 32-bit, x86_64 is 64-bit. Specifying both 32-bit and 64-bit means building universal binaries. 571 | 572 | ### Optimization Options 573 | 574 | WITH_SSE2 (BOOL): Build with SSE2 CPU instructions support (Intel architecture only). 575 | 576 | WITH_NEON (BOOL): Build with NEON CPU instructions support (ARM architecture only). 577 | 578 | ### Client Options 579 | 580 | WITH_CLIENT (BOOL [ON]): Build clients 581 | 582 | WITH_CLIENT_CHANNELS (BOOL [ON]): Build client channels. 583 | 584 | ### Server Options 585 | 586 | WITH_SERVER (BOOL [OFF]): Build servers 587 | 588 | WITH_SERVER_CHANNELS (BOOL [OFF]): Build server channels. 589 | 590 | ### Channel Options 591 | 592 | WITH_CHANNELS (BOOL [ON]): Build channels. 593 | 594 | Channel Names: 595 | 596 | * AUDIN (Audio Input) 597 | * CLIPRDR (Clipboard Redirection) 598 | * DRIVE (Drive / File System Redirection) 599 | * DRDYNVC (Dynamic Virtual Channel) 600 | * PARALLEL (Parallel Port Redirection) 601 | * PRINTER (Printer Redirection) 602 | * RAIL (Remote Applications) 603 | * RDPDR (Device Redirection) 604 | * RDPSND (Audio Output) 605 | * SERIAL (Serial Port Redirection) 606 | * SMARTCARD (Smart Card Redirection) 607 | * TSMF (Multimedia Redirection) 608 | * URBDRC (USB Redirection) 609 | 610 | CHANNEL_ (BOOL): Build channels 611 | 612 | CHANNEL_NAME_CLIENT (BOOL): Build client channel. This option is dependent on CHANNEL_. 613 | 614 | CHANNEL_NAME_SERVER (BOOL): Build server channel. This option is dependent on CHANNEL_. 615 | 616 | ### Feature Options 617 | 618 | WITH_JPEG: Build with JPEG codec support. This feature is not part of the canonical RDP specifications, and is implemented as an alternative codec to RemoteFX or NSCodec. 619 | 620 | WITH_WIN8: Build with Windows 8 support. This is used by the Windows FreeRDP server and enables linking against Windows 8 libraries, therefore breaking backwards compatibility. 621 | 622 | # Testing 623 | 624 | ### CTest 625 | 626 | CTest unit tests are located in “test” subdirectories and are deeply integrated with the rest of the CMake family of software process tools. CTest unit tests do not need a particular test framework. Test code is written as simple programs which return an exit code indicating success or failure. 627 | 628 | CTest unit tests can be enabled with the BUILD_TESTING option. 629 | 630 | #### Introduction 631 | 632 | All unit tests can be executed by invoking ctest with no option: 633 | 634 | ctest . 635 | 636 | Unit tests can be filtered by name using a regular expression and the –R option. 637 | 638 | To run all tests with a name beginning with “TestPath”, use: 639 | 640 | ctest –R “TestPath*” . 641 | 642 | To execute only the “TestPathCchAppend” test, use: 643 | 644 | ctest –R “TestPathCchAppend$” . 645 | 646 | Debug output is turned off by default, but it can be enabled with the –V (verbose) option: 647 | 648 | ctest –V –R “TestPathCchAppend$” . 649 | 650 | # FreeRDS 651 | 652 | These instructions are preliminary for those who want to try FreeRDS as it is being developed. 653 | 654 | ## Getting Started 655 | 656 | Install the dependencies for FreeRDS as instructed in the FreeRDP section of this manual. 657 | 658 | Clone the FreeRDP repository with the FreeRDS development branch: 659 | 660 | mkdir ~/git/FreeRDP 661 | cd ~/git/FreeRDP 662 | git clone git://github.com/FreeRDP/FreeRDP.git 663 | 664 | Clone the FreeRDS development repository in the server directory of the FreeRDP source tree: 665 | 666 | cd ~/git/FreeRDP/FreeRDP/server 667 | git clone git://github.com/FreeRDS/FreeRDS.git 668 | 669 | The FreeRDP git repository automatically ignores the server/FreeRDS directory, such that you can manage the two git repositories independently. Ignoring FreeRDS in the FreeRDP git repository prevents accidental commits where the FreeRDS sources would be included. 670 | 671 | Follow the regular instructions for building FreeRDP, with the exception of a few extra options (WITH_SERVER, WITH_X11RDP). It is currently much easier to deploy FreeRDS to a temporary directory in order to execute it. For the purpose of this example, let's use /opt/freerds as an installation prefix: 672 | 673 | sudo mkdir /opt/freerds 674 | sudo chmod 777 /opt/freerds 675 | 676 | ## Building 677 | 678 | ## X11rdp 679 | 680 | X11rdp is an alternative X11 server like Xvnc, Xephyr, Xnest and Xvb. Normally, these servers are built alongside Xorg with the xorg-server sources as they make use of internal APIs and libraries that are not installed. To build X11rdp, we need to build the xorg-server sources in a known directory such that we can include them in our cmake project. 681 | 682 | The generic approach is to install all the distribution-provided packages required to build the xorg-server package from source. You can then obtain the distribution-sources for the xorg-server package or obtain vanilla sources corresponding to the same version. This process is automated with cmake build scripts, but needs to be done prior to generating the FreeRDS project: 683 | 684 | cd ~/git/FreeRDP/FreeRDP/server/FreeRDS 685 | cd session-manager/module/X11/service/xorg-build 686 | cmake . 687 | make 688 | 689 | If all goes well, you should have xorg-server built in external/Source/xorg-server. Create a symbolic link to that location from session-manager/module/X11/server/xorg-server: 690 | 691 | cd .. 692 | ln -s xorg-build/external/Source/xorg-server xorg-server 693 | 694 | session-manager/module/X11/server/xorg-server will then be picked up by the FreeRDS build system. 695 | 696 | ### FreeRDS 697 | 698 | When generating project files with cmake, specify the prefix using -DCMAKE_INSTALL_PREFIX=/opt/freerds: 699 | 700 | cmake -DWITH_SERVER=on -DWITH_X11RDP=on -DCMAKE_INSTALL_PREFIX=/opt/freerds . 701 | 702 | Then always execute "make install" after building and launch freerds from its installed location. Executing from the source tree may be properly supported in the future but for now it is not recommended. 703 | 704 | ## Firewall 705 | 706 | On distributions with iptables (CentOS, etc), you can turn the firewall off for testing: 707 | 708 | service iptables save 709 | service iptables stop 710 | chkconfig iptables off 711 | 712 | On distributions with UFW (Uncomplicated Firewall) such as Ubuntu and Linux Mint, you can allow port 3389: 713 | 714 | sudo ufw allow 3389/tcp 715 | 716 | ## Running 717 | 718 | Open two terminals logged in as root, and change directory to your installation prefix (/opt/freerds). 719 | 720 | In the first one, execute freerds: 721 | 722 | ./bin/freerds --nodaemon 723 | 724 | In the second one, execute freerds-session-manager: 725 | 726 | ./bin/freerds-session-manager --nodaemon 727 | 728 | There are easier ways of executing freerds but this manual execution method is more flexible for development purposes. 729 | 730 | You can then connect locally: 731 | 732 | ./bin/xfreerdp /u:username /p:password /cert-ignore /v:localhost 733 | ./bin/xfreerdp /u:username /p:password /cert-ignore /v:localhost /rfx 734 | 735 | # API Reference 736 | 737 | ## Input 738 | 739 | ### Concepts 740 | 741 | **Keyboard Type** 742 | 743 | Physical keyboard type used in Windows keyboard layouts. In the vast majority of cases, type 4 (IBM keyboard) is used. Keyboard type 7 (Japanese 109 keyboard) is used with Japanese keyboard layouts. Most other keyboard types are archaic and are most likely irrelevant today, like type 1 (Olivetti 102 keyboard). Complete keyboard type information also includes a keyboard subtype and number of function keys. Virtual scan code values used in RDP are relative to a specific keyboard type, which is in most cases, but not always, keyboard type 4. This means one should not create static keyboard maps directly involving virtual scan codes, since this approach ignores the keyboard type information and is therefore flawed by design for a minority of cases. Instead, developers are encouraged to create keyboard maps using virtual key codes, and generate on-the-fly a keyboard map to virtual scan codes using the winpr-input module. 744 | 745 | **Virtual Scan Code** 746 | 747 | A virtual scan code is a scan code corresponding to a physical key on a given keyboard type. A virtual scan code value ranges from 0 to 127 and is either extended or non-extended. Here are some sample mappings between a keyboard type, virtual scan code, and extended/non-extended flag to help understand the differences: 748 | 749 | * (Type4, 0x1C, NonExtended) = VK_RETURN (regular Enter key) 750 | * (Type4, 0x1C, Extended) = VK_RETURN (keypad Enter key) 751 | * (Type4, 0x1E, NonExtended) = VK_KEY_A (physical 'A' key when using a qwerty layout) 752 | * (Type4, 0x1E, Extended) = VK_NONE (no corresponding virtual key code) 753 | * (Type7, 0x70, NonExtended) = VK_DBE_KATAKANA (special japanese key) 754 | * (Type4, 0x70, NonExtended) = VK_NONE (no corresponding virtual key code) 755 | 756 | **Virtual Key Code** 757 | 758 | Windows virtual key codes are a keyboard-independent codes representing a keyboard key. They are *not* in any way representative of output characters that results from keyboard input. Not all virtual key codes are given names, and information about some of the less frequently used codes is spread out. For the sake of convenience, WinPR provides an exhaustive list of known virtual key codes in winpr/input.h. Since letter keys are not given official names, WinPR defines VK_KEY_LETTER, where each letter key matches the corresponding key on a US qwerty layout. This means that VK_KEY_Q (top left) is still VK_KEY_Q on an azerty keyboard, even if the corresponding physical key has the letter 'A' on an azerty layout. Mapping virtual key codes to corresponding output characters is the keyboard layout's job. 759 | 760 | **Keyboard Layout** 761 | 762 | Keyboard layouts on Windows are implemented using DLLs which export some information about them (keyboard type information) and static data structures used for mapping virtual key code input to output characters. A keyboard layout is uniquely identified by an id, such as 0x00000409 for the US keyboard layout. 763 | 764 | The process of mapping virtual key code input to output characters is a non-invertible function, meaning that output characters cannot be correctly mapped to the original virtual key code input without loss of information. For instance, the capital letter 'A' can be produced by pressing the 'A' key while the shift key is down, or when caps locks is toggled. Using only the output character 'A', it is impossible to know if the character was produced using the shift key or the caps lock key. The same problem occurs for cases for keys which do not directly produce output characters, such as the control or alt keys. With no output characters to try mapping to original virtual key codes, there's not much that can be done. Other cases which prevent proper mapping of output characters to input virtual key codes are dead keys, or keys which do not result in a direct character output but affect the next key press. In many non-US keyboard layouts, accented letters are typed by first pressing a key corresponding to the accent and then typing the letter that needs to be accented. In theory, one can get by creating keyboard layout specific maps, but this is a tedious process that needs to be repeated for every keyboard layout in existence, while being broken by design. 765 | 766 | ### Keyboard Mapping 767 | 768 | WinPR (winpr-input module) offers reusable keyboard mapping utilities to help implementers with providing exhaustive, accurate keyboard support. Include winpr/input.h to make use of these. 769 | 770 | To make debugging and parsing easier, functions are provided to match known key names to their numerical values: 771 | 772 | char* GetVirtualKeyName(DWORD vkcode); 773 | DWORD GetVirtualKeyCodeFromName(const char* vkname); 774 | DWORD GetVirtualKeyCodeFromXkbKeyName(const char* xkbname); 775 | 776 | Example: mapping XKB key name to virtual key code and printing out the conversion result: 777 | 778 | ~~~ 779 | char* xkbname = "RTRN"; /* XKB Enter key */ 780 | DWORD vkcode = GetVirtualKeyCodeFromXkbKeyName(xkbname); /* returns VK_RETURN */ 781 | printf("XKB key name: %s Virtual Key Code %s (0x%04X)\n", xkbname, GetVirtualKeyName(vkcode), vkcode); 782 | ~~~ 783 | 784 | Example: converting textual representation of a virtual key to its corresponding numerical value: 785 | 786 | ~~~ 787 | char* vkname = "VK_RETURN"; /* this string could be obtained from a configuration file instead */ 788 | DWORD vkcode = GetVirtualKeyCodeFromName(vkname); 789 | printf("Virtual Key Code: %s (0x%04X)\n", vkname, vkcode); 790 | ~~~ 791 | 792 | When mapping keyboard systems, the general approach is to create a map between the native key codes and virtual key codes. However, since RDP uses virtual scan codes, you will still need to map the virtual key codes to virtual scan codes before sending them. The advantage is that virtual scan codes are truly keyboard independent and have proper names, while virtual scan codes are highly impractical from the fact that they don't really have names other than their number and are prone to change with regards to the physical keyboard type in use. If the only data you can have from the local input system is output characters, you should attempt using unicode input instead and limit usage of non-unicode keyboard input events to non-character input for keys like shift and num lock. 793 | 794 | DWORD GetVirtualKeyCodeFromVirtualScanCode(DWORD scancode, DWORD dwKeyboardType); 795 | DWORD GetVirtualScanCodeFromVirtualKeyCode(DWORD vkcode, DWORD dwKeyboardType); 796 | 797 | Example: mapping virtual key codes to virtual scan codes: 798 | 799 | ~~~ 800 | DWORD scancode; 801 | 802 | /* Regular Enter key (non-extended) */ 803 | scancode = GetVirtualScanCodeFromVirtualKeyCode(VK_RETURN, 4); /* returns 0x1C */ 804 | 805 | /* Keypad Enter key (extended) */ 806 | scancode = GetVirtualScanCodeFromVirtualKeyCode(VK_RETURN | KBDEXT, 4); /* returns (0x1C | KBDEXT) */ 807 | ~~~ 808 | 809 | Example: mapping virtual scan codes to virtual key codes: 810 | 811 | ~~~ 812 | DWORD vkcode; 813 | 814 | /* Regular Enter key (non-extended) */ 815 | vkcode = GetVirtualKeyCodeFromVirtualScanCode(0x1C, 4); /* returns VK_RETURN */ 816 | 817 | /* Keypad Enter key (extended) */ 818 | vkcode = GetVirtualKeyCodeFromVirtualScanCode(0x1C | KBDEXT, 4); /* returns (VK_RETURN | KBDEXT) */ 819 | ~~~ 820 | 821 | Certain keyboard systems use key codes which can be statically mapped to virtual key codes. WinPR currently provides mapping for Linux evdev and Mac OS X keycodes: 822 | 823 | DWORD GetVirtualKeyCodeFromKeycode(DWORD keycode, DWORD dwFlags); 824 | DWORD GetKeycodeFromVirtualKeyCode(DWORD keycode, DWORD dwFlags); 825 | 826 | dwFlags: 827 | * KEYCODE_TYPE_APPLE 828 | * KEYCODE_TYPE_EVDEV 829 | 830 | Most modern Linux X11 environments used evdev for input devices. The good news is that evdev uses a static set of X11 keycodes, which is not the case in other X11 environments. When evdev is not in use but XKB is available, a dynamic keyboard map can be generated on-the-fly using the XKB keyboard mapping utilities. One can use the xev utility to test keyboard input and see X11 keycodes. The following is a sample xev output for the 'A' key on a Linux system using evdev: 831 | 832 | ~~~ 833 | KeyPress event, serial 40, synthetic NO, window 0x5600001, 834 | root 0xd9, subw 0x0, time 17400104, (4,14), root:(1039,482), 835 | state 0x2000, keycode 38 (keysym 0x61, a), same_screen YES, 836 | XLookupString gives 1 bytes: (61) "a" 837 | XmbLookupString gives 1 bytes: (61) "a" 838 | XFilterEvent returns: False 839 | 840 | KeyRelease event, serial 40, synthetic NO, window 0x5600001, 841 | root 0xd9, subw 0x0, time 17400214, (4,14), root:(1039,482), 842 | state 0x2000, keycode 38 (keysym 0x61, a), same_screen YES, 843 | XLookupString gives 1 bytes: (61) "a" 844 | XFilterEvent returns: False 845 | ~~~ 846 | 847 | Example: mapping Linux evdev keycode to virtual key code back and forth: 848 | 849 | ~~~ 850 | DWORD vkcode; 851 | DWORD keycode = 38; /* evdev 'A' key */ 852 | vkcode = GetVirtualKeyCodeFromKeycode(keycode, KEYCODE_TYPE_EVDEV); /* returns VK_KEY_A */ 853 | keycode = GetKeycodeFromVirtualKeyCode(vkcode, KEYCODE_TYPE_EVDEV); /* returns 38 */ 854 | ~~~ 855 | 856 | Mac OS X uses the same set of keycodes in X11 and non-X11 environments. While values from 0 to 7 are unused, the keyCode member of the NSEvent class is off by 8. This means that when receiving the keycode value from Mac OS X, you should increment it by 8 before passing it to GetVirtualKeyCodeFromKeycode(), and decrement the keycode value returned by GetKeycodeFromVirtualKeyCode() before passing it to Mac OS X. 857 | 858 | Example: mapping Mac OS X keycode to virtual key code back and forth: 859 | 860 | ~~~ 861 | DWORD vkcode; 862 | DWORD keycode = APPLE_VK_Return; /* Mac OS X Enter key */ 863 | vkcode = GetVirtualKeyCodeFromKeycode(keycode + 8, KEYCODE_TYPE_APPLE); /* returns VK_RETURN */ 864 | keycode = GetKeycodeFromVirtualKeyCode(vkcode, KEYCODE_TYPE_APPLE) - 8; /* returns APPLE_VK_Return */ 865 | ~~~ 866 | 867 | ### Synchronize Event 868 | 869 | An RDP synchronize event is used to synchronize keyboard toggle keys, such as caps lock and num lock. Synchronization of toggle keys is usually required whenever the local session window gains focus, as toggle key states may have changed while the window was not focused. 870 | 871 | void freerdp_input_send_synchronize_event(rdpInput* input, UINT32 flags); 872 | 873 | flags: 874 | 875 | * KBD_SYNC_SCROLL_LOCK 876 | * KBD_SYNC_NUM_LOCK 877 | * KBD_SYNC_CAPS_LOCK 878 | * KBD_SYNC_KANA_LOCK 879 | 880 | Each flag should be set only if the corresponding key is toggled on the local keyboard. The Kana Lock key is only meaningful for Japanese keyboard input. 881 | 882 | ### Keyboard Event 883 | 884 | An RDP keyboard event is a message containing a Windows virtual scan code (extended or non-extended) along with flags to mark the corresponding key as being up or down. 885 | 886 | void freerdp_input_send_keyboard_event(rdpInput* input, UINT16 flags, UINT16 code); 887 | 888 | flags: 889 | 890 | * KBD_FLAGS_EXTENDED 891 | * KBD_FLAGS_RELEASE 892 | * KBD_FLAGS_DOWN 893 | 894 | ### Keyboard Unicode Event 895 | 896 | An RDP unicode keyboard event is a message containing a unicode character along with flags to mark the key as being released. 897 | 898 | void freerdp_input_send_unicode_keyboard_event(rdpInput* input, UINT16 flags, UINT16 code); 899 | 900 | flags: 901 | 902 | * KBD_FLAGS_RELEASE 903 | 904 | Example: sending 'A' unicode character: 905 | 906 | ~~~ 907 | freerdp_input_send_unicode_keyboard_event(input, 0, 0x0041); /* Unicode 'A' character (key down) */ 908 | freerdp_input_send_unicode_keyboard_event(input, KBD_FLAGS_RELEASE, 0x0041); /* Unicode 'A' character (key up) */ 909 | ~~~ 910 | 911 | ### Mouse Event 912 | 913 | An RDP mouse event is used for standard mouse buttons (left, middle and right), mouse movement and mouse wheel scrolling. 914 | 915 | void freerdp_input_send_mouse_event(rdpInput* input, UINT16 flags, UINT16 x, UINT16 y); 916 | 917 | flags: 918 | 919 | * PTR_FLAGS_DOWN 920 | * PTR_FLAGS_MOVE 921 | * PTR_FLAGS_BUTTON1 (left) 922 | * PTR_FLAGS_BUTTON2 (right) 923 | * PTR_FLAGS_BUTTON3 (middle) 924 | * PTR_FLAGS_WHEEL 925 | * PTR_FLAGS_WHEEL_NEGATIVE 926 | * WheelRotationMask 927 | 928 | Example: mouse left-click: 929 | 930 | ~~~ 931 | freerdp_input_send_mouse_event(input, PTR_FLAGS_BUTTON1 | PTR_FLAGS_DOWN, 100, 200); 932 | freerdp_input_send_mouse_event(input, PTR_FLAGS_BUTTON1, 100, 200); 933 | ~~~ 934 | 935 | Example: mouse movement: 936 | 937 | ~~~ 938 | freerdp_input_send_mouse_event(input, PTR_FLAGS_MOVE, 100, 200); 939 | ~~~ 940 | 941 | Example: mouse wheel scrolling: 942 | 943 | ~~~ 944 | int rotationUnits = 0x0078; 945 | freerdp_input_send_mouse_event(input, PTR_FLAGS_WHEEL | (rotationUnits & WheelRotationMask), 0, 0); 946 | freerdp_input_send_mouse_event(input, PTR_FLAGS_WHEEL | (rotationUnits & WheelRotationMask) | PTR_FLAGS_WHEEL_NEGATIVE, 0, 0); 947 | ~~~ 948 | 949 | ### Extended Mouse Event 950 | 951 | An RDP extended mouse event is used for extended mouse buttons, such as button 4 and 5. The extended mouse event accepts the same flags as the regular mouse event, with a few extended flags. 952 | 953 | void freerdp_input_send_extended_mouse_event(rdpInput* input, UINT16 flags, UINT16 x, UINT16 y); 954 | 955 | flags: 956 | 957 | * PTR_XFLAGS_DOWN 958 | * PTR_XFLAGS_BUTTON1 (button 4) 959 | * PTR_XFLAGS_BUTTON2 (button 5) 960 | 961 | Example: extended mouse click 962 | 963 | ~~~ 964 | freerdp_input_send_extended_mouse_event(input, PTR_XFLAGS_BUTTON1 | PTR_XFLAGS_DOWN, 100, 200); 965 | freerdp_input_send_extended_mouse_event(input, PTR_XFLAGS_BUTTON1, 100, 200); 966 | ~~~ 967 | 968 | ## Virtual Channel API 969 | 970 | [Virtual Channel Client DLL](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383580 "Virtual Channel Client DLL") 971 | 972 | ### VirtualChannelEntry 973 | 974 | ~~~ 975 | typedef BOOL VCAPITYPE VIRTUALCHANNELENTRY(PCHANNEL_ENTRY_POINTS pEntryPoints); 976 | ~~~ 977 | 978 | VirtualChannelEntry is the entry point of static virtual channel clients. This function is called with a pointer to a CHANNEL_ENTRY_POINTS structure containing the portion of the virtual channel API exposed to the virtual channel client: 979 | 980 | ~~~ 981 | typedef struct tagCHANNEL_ENTRY_POINTS 982 | { 983 | DWORD cbSize; 984 | DWORD protocolVersion; 985 | PVIRTUALCHANNELINIT pVirtualChannelInit; 986 | PVIRTUALCHANNELOPEN pVirtualChannelOpen; 987 | PVIRTUALCHANNELCLOSE pVirtualChannelClose; 988 | PVIRTUALCHANNELWRITE pVirtualChannelWrite; 989 | } CHANNEL_ENTRY_POINTS, *PCHANNEL_ENTRY_POINTS; 990 | ~~~ 991 | 992 | The data contained within this structure is only valid for the duration of the call to VirtualChannelEntry and should therefore be copied. 993 | 994 | ### VirtualChannelInit 995 | 996 | VirtualChannelInit has to be called by the virtual channel client when VirtualChannelEntry is called. 997 | 998 | ~~~ 999 | typedef UINT VCAPITYPE VIRTUALCHANNELINIT(LPVOID* ppInitHandle, PCHANNEL_DEF pChannel, INT channelCount, ULONG versionRequested, PCHANNEL_INIT_EVENT_FN pChannelInitEventProc); 1000 | 1001 | typedef VIRTUALCHANNELINIT *PVIRTUALCHANNELINIT; 1002 | ~~~ 1003 | 1004 | ppInitHandle receives the init handle which is used to identify the current connection when calling [VirtualChannelOpen](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383570 "VirtualChannelOpen"). 1005 | 1006 | pChannel is an array of CHANNEL_DEF structures, where the number of elements in the array is given by channelCount. 1007 | 1008 | ~~~ 1009 | typedef struct tagCHANNEL_DEF 1010 | { 1011 | char name[CHANNEL_NAME_LEN + 1]; 1012 | ULONG options; 1013 | } CHANNEL_DEF; 1014 | typedef CHANNEL_DEF *PCHANNEL_DEF; 1015 | typedef PCHANNEL_DEF *PPCHANNEL_DEF; 1016 | ~~~ 1017 | 1018 | ### VirtualChannelInitEvent 1019 | 1020 | [VirtualChannelInitEvent](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383568 "VirtualChannelInitEvent"): 1021 | 1022 | ~~~ 1023 | typedef VOID VCAPITYPE CHANNEL_INIT_EVENT_FN(LPVOID pInitHandle, UINT event, LPVOID pData, UINT dataLength); 1024 | 1025 | typedef CHANNEL_INIT_EVENT_FN *PCHANNEL_INIT_EVENT_FN; 1026 | ~~~ 1027 | 1028 | ### VirtualChannelOpen 1029 | 1030 | [VirtualChannelOpen](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383570 "VirtualChannelOpen") should be called for each channel registered by the current virtual channel client when VirtualChannelInitEvent is called with a CHANNEL_EVENT_CONNECTED event. 1031 | 1032 | ~~~ 1033 | typedef UINT VCAPITYPE VIRTUALCHANNELOPEN(LPVOID pInitHandle, LPDWORD pOpenHandle, PCHAR pChannelName, PCHANNEL_OPEN_EVENT_FN pChannelOpenEventProc); 1034 | 1035 | typedef VIRTUALCHANNELOPEN *PVIRTUALCHANNELOPEN; 1036 | ~~~ 1037 | 1038 | VirtualChannelOpen takes the init handle obtained by a previous call to VirtualChannelInit and receives an open handle which will be used in calls to VirtualChannelWrite and VirtualChannelClose. A pointer to a [VirtualChannelOpenEvent](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383573 "VirtualChannelOpenEvent") function is also passed to VirtualChannelOpen which will be used to receive notifications for read and write operations. 1039 | 1040 | ### VirtualChannelOpenEvent 1041 | 1042 | [VirtualChannelOpenEvent](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383573 "VirtualChannelOpenEvent") is used to notify the virtual channel client of data being received or the completion of data write operations. 1043 | 1044 | ~~~ 1045 | typedef VOID VCAPITYPE CHANNEL_OPEN_EVENT_FN(DWORD openHandle, UINT event, LPVOID pData, UINT32 dataLength, UINT32 totalLength, UINT32 dataFlags); 1046 | 1047 | typedef CHANNEL_OPEN_EVENT_FN *PCHANNEL_OPEN_EVENT_FN; 1048 | ~~~ 1049 | 1050 | ### VirtualChannelWrite 1051 | 1052 | Virtual channel clients call [VirtualChannelWrite](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383576 "VirtualChannelWrite") with the open handle obtained by calling VirtualChannelOpen in order to write data to the virtual channel. 1053 | 1054 | ~~~ 1055 | typedef UINT VCAPITYPE VIRTUALCHANNELWRITE(DWORD openHandle, LPVOID pData, ULONG dataLength, LPVOID pUserData); 1056 | 1057 | typedef VIRTUALCHANNELWRITE *PVIRTUALCHANNELWRITE; 1058 | ~~~ 1059 | 1060 | ### VirtualChannelClose 1061 | 1062 | [VirtualChannelClose](http://msdn.microsoft.com/en-us/library/windows/desktop/aa383556 "VirtualChannelClose") is called by the virtual channel close using the open handle returned by the previous call to VirtualChannelOpen to close the virtual channel. 1063 | 1064 | ~~~ 1065 | typedef UINT VCAPITYPE VIRTUALCHANNELCLOSE(DWORD openHandle); 1066 | 1067 | typedef VIRTUALCHANNELCLOSE *PVIRTUALCHANNELCLOSE; 1068 | ~~~ 1069 | -------------------------------------------------------------------------------- /Developer/FreeRDP-Developer-Manual.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/Developer/FreeRDP-Developer-Manual.pdf -------------------------------------------------------------------------------- /Testing/FreeRDP-Testing-Manual.markdown: -------------------------------------------------------------------------------- 1 | % FreeRDP Testing Manual 2 | % Marc-André Moreau 3 | % Awake Coding Consulting Inc. 4 | 5 | # Introduction 6 | 7 | ## References 8 | 9 | [FreeRDP User Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/User/FreeRDP-User-Manual.pdf?raw=true "FreeRDP User Manual") 10 | 11 | [FreeRDP Developer Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Developer/FreeRDP-Developer-Manual.pdf?raw=true "FreeRDP Developer Manual") 12 | 13 | [FreeRDP Configuration Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Configuration/FreeRDP-Configuration-Manual.pdf?raw=true "FreeRDP Configuration Manual") 14 | 15 | # Serial Redirection 16 | 17 | 18 | Connect an usb2serial converter (no need to connect a device) 19 | 20 | Run xfreerdp /serial:COM10,/dev/ttyUSB0 /u:demo1 /p:qw /v:servername 21 | 22 | Inside the rdp session open a cmd and verify that the port got mapped to COM10 using the change port /query command. This should give the following (or similar) output: 23 | 24 | change port /query 25 | AUX = \DosDevices\COM1 26 | COM1 = \Device\Serial0 27 | COM2 = \Device\Serial1 28 | COM10 = \Devices\RdpDrPort\;COM10:2\tsclient\COM10 29 | 30 | Install [Putty](http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) 31 | 32 | Install [HyperTerminal](http://www.hilgraeve.com/support/htpe7.exe) (30-day trial) 33 | 34 | Open Putty, select (*) serial, enter COM10 in the serial line edit and click the Open button: 35 | xfreerdp's CPU usage will immediately raise (25% on my Linux-iMac) to a constant high level until you close putty 36 | 37 | Open HyperTerminal, select Menu->File->New Connection, name it COM-10, select COM10 from the "connect using:" dropdown, click ok and again on ok in the next dialog. 38 | xfreerdp's CPU usage will immediately increase but less compared to Putty (5% on my box) 39 | 40 | Additional Information 41 | 42 | Putty and HyperTerminal both use [SetCommTimeouts](http://msdn.microsoft.com/en-us/library/windows/desktop/aa363437). 43 | Putty uses 1ms for ReadIntervalTimeout and Hyperterm 10ms. 44 | 45 | Using mstsc I see literally no CPU usage. 46 | -------------------------------------------------------------------------------- /Testing/FreeRDP-Testing-Manual.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/Testing/FreeRDP-Testing-Manual.pdf -------------------------------------------------------------------------------- /User/FreeRDP-User-Manual.markdown: -------------------------------------------------------------------------------- 1 | % FreeRDP User Manual 2 | % Marc-André Moreau 3 | % Awake Coding Consulting Inc. 4 | 5 | # Introduction 6 | 7 | ## References 8 | 9 | [FreeRDP Developer Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Configuration/FreeRDP-Developer-Manual.pdf?raw=true "FreeRDP Developer Manual") 10 | 11 | [FreeRDP Configuration Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Configuration/FreeRDP-Configuration-Manual.pdf?raw=true "FreeRDP Configuration Manual") 12 | 13 | [FreeRDP Testing Manual](https://github.com/awakecoding/FreeRDP-Manuals/blob/master/Testing/FreeRDP-Testing-Manual.pdf?raw=true "FreeRDP Testing Manual") 14 | 15 | ## Help 16 | 17 | FreeRDP - A Free Remote Desktop Protocol Implementation 18 | 19 | See www.freerdp.com for more information 20 | 21 | Usage: xfreerdp [file] [options] [/v:[:port]] 22 | 23 | Syntax: 24 | 25 | /flag (enables flag) 26 | /option: (specifies option with value) 27 | +toggle -toggle (enables or disables toggle, where '/' is a synonym of '+') 28 | 29 | /v:[:port] Server hostname 30 | /port: Server port 31 | /w: Width 32 | /h: Height 33 | /size:x Screen size 34 | /f Fullscreen mode 35 | /bpp: Session bpp (color depth) 36 | /kbd:0x or Keyboard layout 37 | /kbd-list List keyboard layouts 38 | /kbd-type: Keyboard type 39 | /kbd-subtype: Keyboard subtype 40 | /kbd-fn-key: Keyboard function key count 41 | /admin Admin (or console) session 42 | /multimon Multi-monitor 43 | /workarea Work area 44 | /t: Window title 45 | +decorations (default:off) Window decorations 46 | /a Addin 47 | /vc Static virtual channel 48 | /dvc Dynamic virtual channel 49 | /u:[<domain>\\]<user> or <user>[@<domain>] Username 50 | /p:<password> Password 51 | /d:<domain> Domain 52 | /g:<gateway>[:port] Gateway Hostname 53 | /gu:[<domain>\\]<user> or <user>[@<domain>] Gateway username 54 | /gp:<password> Gateway password 55 | /gd:<domain> Gateway domain 56 | /app:||<alias> or <executable path> Remote application program 57 | /app-name:<app name> Remote application name for user interface 58 | /app-icon:<icon path> Remote application icon for user interface 59 | /app-cmd:<parameters> Remote application command-line parameters 60 | /app-file:<file name> File to open with remote application 61 | /app-guid:<app guid> Remote application GUID 62 | +compression (default:off) Compression 63 | /shell Alternate shell 64 | /shell-dir Shell working directory 65 | /audio-mode Audio output mode 66 | /mic Audio input (microphone) 67 | /network Network connection type 68 | +clipboard (default:off) Redirect clipboard 69 | +fonts (default:off) Smooth fonts (cleartype) 70 | +aero (default:off) Desktop composition 71 | +window-drag (default:off) Full window drag 72 | +menu-anims (default:off) Menu animations 73 | -themes (default:on) Themes 74 | -wallpaper (default:on) Wallpaper 75 | /gdi:<sw|hw> GDI rendering 76 | /rfx RemoteFX 77 | /rfx-mode:<image|video> RemoteFX mode 78 | /frame-ack:<number> Frame acknowledgement 79 | /nsc NSCodec 80 | /jpeg JPEG codec 81 | /jpeg-quality:<percentage> JPEG quality 82 | -nego (default:on) protocol security negotiation 83 | /sec:<rdp|tls|nla|ext> force specific protocol security 84 | -sec-rdp (default:on) rdp protocol security 85 | -sec-tls (default:on) tls protocol security 86 | -sec-nla (default:on) nla protocol security 87 | +sec-ext (default:off) nla extended protocol security 88 | /cert-name:<name> certificate name 89 | /cert-ignore ignore certificate 90 | /pcb:<blob> Preconnection Blob 91 | /pcid:<id> Preconnection Id 92 | /vmconnect:<vmid> Hyper-V console (use port 2179, disable negotiation) 93 | -authentication (default:on) authentication (hack!) 94 | -encryption (default:on) encryption (hack!) 95 | -grab-keyboard (default:on) grab keyboard 96 | -mouse-motion (default:on) mouse-motion 97 | /parent-window:<window id> Parent window id 98 | -bitmap-cache (default:on) bitmap cache 99 | -offscreen-cache (default:on) offscreen bitmap cache 100 | -glyph-cache (default:on) glyph cache 101 | /codec-cache:<rfx|nsc|jpeg> bitmap codec cache 102 | -fast-path (default:on) fast-path input/output 103 | +async-input (default:off) asynchronous input 104 | +async-update (default:off) asynchronous update 105 | /version print version 106 | /help print help 107 | 108 | Examples: 109 | 110 | xfreerdp connection.rdp /p:Pwd123! /f 111 | xfreerdp /u:CONTOSO\\JohnDoe /p:Pwd123! /v:rdp.contoso.com 112 | xfreerdp /u:JohnDoe /p:Pwd123! /w:1366 /h:768 /v:192.168.1.100:4489 113 | xfreerdp /u:JohnDoe /p:Pwd123! /vmconnect:C824F53E-95D2-46C6-9A18-23A5BB403532 /v:192.168.1.100 114 | 115 | Clipboard Redirection: +clipboard 116 | 117 | Drive Redirection: /a:drive,home,/home 118 | Smartcard Redirection: /a:smartcard,<device> 119 | Printer Redirection: /a:printer,<device>,<driver> 120 | Serial Port Redirection: /a:serial,<device> 121 | Parallel Port Redirection: /a:parallel,<device> 122 | Printer Redirection: /a:printer,<device>,<driver> 123 | 124 | Audio Input Redirection: /dvc:audin,sys:alsa 125 | Audio Output Redirection: /vc:rdpsnd,sys:alsa 126 | 127 | Multimedia Redirection: /dvc:tsmf,sys:alsa 128 | USB Device Redirection: /dvc:urbdrc,id,dev:054c:0268 129 | 130 | ## Command-Line Interface 131 | 132 | As of FreeRDP 1.1, the command-line interface supports two syntaxes and a completely redesigned set of command-line options. Since this is a major change, backwards compatibility is still provided for the now deprecated old command-line interface. 133 | 134 | FreeRDP uses the same command-line syntax and options as mstsc as a basis, allowing a consistent interface between RDP implementations. The mstsc help can be obtained by launching mstsc with the /? option: 135 | 136 | ![mstsc help](images/mstsc_help.png "mstsc help") 137 | 138 | On top of this basic set of options, FreeRDP provides a large selection of extended options to fit all needs possible. The result is a compatible and consistent RDP implementation which is much more flexible and extensible than the original. This is why FreeRDP is used on Windows, where mstsc is already available for free. 139 | 140 | ## Syntax 141 | 142 | FreeRDP supports two command-line syntaxes: the default windows-style syntax and the alternative posix-style syntax. This is made possible by a generic and highly reusable command-line parsing engine that is part of WinPR. On average, the windows-style syntax provides shorter command lines than the posix-style syntax. However, many users tend to prefer the posix-style syntax and may strongly dislike the windows-style syntax, which is why *both* syntaxes are supported. For the purpose of documenting FreeRDP, the windows-style syntax is preferred over the posix-style syntax. 143 | 144 | There are three types of options possible: 145 | 146 | /flag (enables flag) 147 | /option:<value> (specifies option with value) 148 | +toggle -toggle (enables or disables toggle, where '/' is a synonym of '+') 149 | 150 | If we observe the following command line: 151 | 152 | xfreerdp /f /bpp:32 /v:rdp.contoso.com +wallpaper -themes 153 | 154 | /f is a flag which enables the fullscreen mode. 155 | /bpp:32 is the "bpp" option that specifies the color depth with a value of 32. 156 | /v:rdp.contoso.com is the "v" option for the target server with rdp.contoso.com as its value. 157 | +wallpaper is an option that enables the wallpaper toggle option. 158 | -themes is an option that disables the themes toggle option. 159 | 160 | Enabling a toggle option can be done with both '+' and '/' for the sake of simplicity. This means that enabling the wallpaper can be done with "+wallpaper" or with "/wallpaper". 161 | 162 | ### Alternate Syntax 163 | 164 | The alternate syntax produces longer command lines on average, but may be more accessible to users who prefer a posix-style syntax. If this is your case, here is how the alternative syntax works: 165 | 166 | --flag (enables flag) 167 | --option:<value> (specifies option with value) 168 | --enable-toggle --disable-toggle (enables or disables toggle) 169 | 170 | Performing syntaxic substitutions on our example, the command line becomes: 171 | 172 | xfreerdp -f --bpp 32 -v rdp.contoso.com --enable-wallpaper --disable-themes 173 | 174 | The same command in the windows-style syntax uses 57 characters, while the posix-style syntax uses 75 characters. In this specific case, the windows-style syntax is approximately 25% shorter than the posix-style syntax. 175 | 176 | ### Deprecated Options 177 | 178 | If the deprecated command-line options are used, FreeRDP warns the user about the deprecation of these options and provides mapping from the old options to the new ones, simplifying migration: 179 | 180 | xfreerdp -f -a 32 --enable-wallpaper --disable-themes rdp.contoso.com 181 | WARNING: Using deprecated command-line interface! 182 | -a 32 -> /bpp:32 183 | -f -> /f 184 | rdp.contoso.com -> /v:rdp.contoso.com 185 | 186 | ### Common Pitfalls 187 | 188 | Supporting two syntaxes along with automated detection of the deprecated options comes with certain pitfalls for the user. There are currently three possible cases for parsing the command line: 189 | 190 | * New options, windows-style syntax 191 | * New options, posix-style syntax 192 | * Old options, posix-style syntax 193 | 194 | The way parsing works is that FreeRDP attempts parsing the command line according to the three possible cases and counts the number of accepted options. The command line is then parsed again for real based on these results. Since the old options had restrictions on the positions of certain arguments like the target server that are not present, this difference is also used to facilitate proper detection of the syntax and options in use. 195 | 196 | Since the command line is parsed according to only one syntax and option set at a time, one *cannot* mix syntaxes and options that belong to different cases. The following example shows incorrect mixing of the command-line syntaxes that will lead to incorrect parsing of some of the options: 197 | 198 | xfreerdp /f --bpp 32 -v rdp.contoso.com +wallpaper -themes 199 | 200 | A valid command line for the above example needs to be either one of the following: 201 | 202 | xfreerdp /f /bpp:32 /v:rdp.contoso.com +wallpaper -themes 203 | xfreerdp -f --bpp 32 -v rdp.contoso.com --enable-wallpaper --disable-themes 204 | 205 | Another common mistake made by users migrating from the old options is to put the target server name as the last argument without an option name: 206 | 207 | xfreerdp -f --bpp 32 --enable-wallpaper --disable-themes rdp.contoso.com 208 | WARNING: Using deprecated command-line interface! 209 | -f -> /f 210 | rdp.contoso.com -> /v:rdp.contoso.com 211 | 212 | The correct command would be: 213 | 214 | xfreerdp -f --bpp 32 --enable-wallpaper --disable-themes -v rdp.contoso.com 215 | 216 | With the new set of options, never forget to use "v" for the target server, otherwise your command line will be interpreted as using the deprecated interface. 217 | 218 | ### Rationale 219 | 220 | One may ask: why, oh why? Well, here's why: 221 | 222 | The first easy answer is out-of-the-box compatibility with mstsc, but there's a lot more to it than just that. 223 | 224 | One of the most annoying aspect of the posix-style syntax is that it uses the minus '-' sign to *enable* an option, preventing unambiguous usage of the same symbol to mean *disable*. Certain programs using a posix-style syntax do accept +/-, but you need to know which options can be toggled in such a manner beforehand. This can easily lead to confusion because one cannot know just by looking at the syntax if the minus '-' sign is used to enable or disable an option, as knowledge of the option type is required to make the distinction. 225 | 226 | In order to unambiguously make use of the minus +/- as a way to toggle options, we need to use a symbol other than minus '-' to enable options. Since the windows-style syntax uses the slash '/' symbol instead, this problem is solved. 227 | 228 | The toggle options are very frequently used in FreeRDP, which is why it makes sense to use a syntax that keeps them short and readable. When you type options like --disable-themes multiple times a day and your command lines contain *many* such options, it is hard to argue against using the +/- notation. 229 | 230 | One other strong aspect of the windows-style syntax is the usage of the colon as an option/value separator instead of a space. While this may require some adaptation for some users, it reduces the potential for ambiguity in the case of values that are lists. Most of the time, windows-style syntaxes encode lists as comma-separated values: 231 | 232 | /list:item1,item2,item3 233 | 234 | With regular posix-style syntax, the same list would be encoded this way: 235 | 236 | --list item1 item2 item3 -- 237 | 238 | In the case of FreeRDP, lists are encoded in the same way regardless of the syntax in use, even if this diverges slightly from standard practice: 239 | 240 | --list item1,item2,item3 241 | 242 | The comma-separated list is used because it provides unambiguous encoding of a list: otherwise, there is no way of knowing where the list ends, which is which the regular posix-style syntax makes use of "--" as the end-of-list delimiter. The old set of FreeRDP options historically made use of this list encoding, and it definitely won't be missed by many users. 243 | 244 | If even after reading this you can't get used to the windows-style syntax, simply make use of the posix-style syntax. 245 | 246 | # Authentication 247 | 248 | Sample Values: 249 | 250 | * User: JohnDoe 251 | * Domain: CONTOSO 252 | * Password: Password123! 253 | * Server: rdp.contoso.com 254 | 255 | There simplest, unambiguous way of passing credentials at the command-line is with /u, /d and /p. The domain name is only needed if you connect using domain credentials: 256 | 257 | xfreerdp /u:JohnDoe /d:CONTOSO /p:Password123! /v:rdp.contoso.com 258 | 259 | The domain name can also be passed in the username using the same notation accepted by mstsc: 260 | 261 | xfreerdp /u:CONTOSO\JohnDoe /p:Password123! /v:rdp.contoso.com 262 | 263 | While the above notation is shorter, it has an unpractical side effect: the backslash is often, but not always, interpreted as an escape character. To avoid the problem, make sure the shell does not interpret the backslash as an escape character: 264 | 265 | xfreerdp /u:CONTOSO\\JohnDoe /p:Password123! /v:rdp.contoso.com 266 | xfreerdp "/u:CONTOSO\JohnDoe" /p:Password123! /v:rdp.contoso.com 267 | 268 | From experience, most Linux shells will require such handling of the backslash character. However, there are certain cases like the Eclipse launcher which do not require it. 269 | 270 | Alternatively, the User Principal Name (UPN) notation can be used: 271 | 272 | xfreerdp /u:JohnDoe@CONTOSO /p:Password123! /v:rdp.contoso.com 273 | 274 | This notation does not have the drawbacks of the backslash character, but introduces a potential conflict with usernames containing the '@' symbol and no domain name. This is frequently the case with the new Windows 8 Microsoft Accounts (a.k.a. Windows Live Accounts) which correspond to an email address. To work work around the ambiguity, precede the user name "john.doe@live.com" with a backslash: 275 | 276 | xfreerdp /u:\john.doe@live.com /p:Password123! /v:rdp.contoso.com 277 | 278 | Be careful to properly handle the backslash character as previously instructed. 279 | 280 | Passwords entered as command-line arguments could potentially be seen by other users on the same system, so they are automatically hidden: 281 | 282 | awake@workstation:~$ ps aux | grep freerdp 283 | awake 22506 0.0 0.1 2502620 10236 s002 S+ 11:10pm 0:01.00 xfreerdp /u:JohnDoe /p:************ /d:CONTOSO /v:rdp.contoso.com 284 | 285 | ## Credentials Prompt 286 | 287 | If you omit entering credentials at the command-line, FreeRDP may prompt you for credentials depending on the negotiated protocol security level. 288 | 289 | ### Protocol Security 290 | 291 | RDP protocol security is confusing for many users because it strongly affects the way credentials can be prompted. There are three main security levels that can be negotiated: 292 | 293 | * RDP Security (old encryption, old authentication) 294 | * TLS Security (TLS encryption, old authentication) 295 | * NLA Security (TLS encryption, NLA authentication) 296 | 297 | #### Old Authentication 298 | 299 | The old RDP authentication mechanism is very simple: the server presents the client with the Winlogon GUI, and the user can either automatically or manually enter the credentials. If you enter credentials prior to connecting to a server with the old authentication, they will be automatically on connection, saving you the trouble of typing them manually. 300 | 301 | Old RDP authentication may be practical in the sense that you can get a remote Winlogon GUI without being authenticated on the server. This is however a design flaw which makes the RDP server vulnerable to a DDOS attack: since significant resources need to be allocated for the Winlogon GUI without being authenticated, a distributed denial of service attack could be performed by simply launching multiple unauthenticated connections. This is exactly why it is no longer possible to obtain such a GUI prior to authentication with newer security levels. 302 | 303 | ![Winlogon GUI](images/winlogon_gui.png "Winlogon GUI") 304 | 305 | #### Network Level Authentication (NLA) 306 | 307 | Network Level Authentication (NLA) is required by default with servers starting with Windows Vista. With NLA, authentication is the very first thing that occurs over the wire, such that the server will only allocate resources and present a graphical interface to authenticated clients. It is also much more secure and provides strong defense mechanisms against Man-in-the-Middle (MITM) attacks. 308 | 309 | When NLA is negotiated, the complete credentials are needed at connection time, which is why FreeRDP will prompt for the missing information: 310 | 311 | xfreerdp /u:JohnDoe /d:CONTOSO /v:rdp.contoso.com 312 | connected to rdp.contoso.com 313 | Password: 314 | 315 | # Performance Flags 316 | 317 | The RDP performance flags are used by the client to tweak certain remote graphical operations affecting the user experience. A good example is the wallpaper: drawing it requires sending a lot of data as opposed to filling it with black. Using the wallpaper is fast enough on the LAN, but it may negatively affect performance over a slower connection such as over a cellular network. The same principle applies for themes, fonts, menu animations, window dragging, etc. 318 | 319 | ## Smooth Fonts 320 | 321 | Disabled by default, enable with +fonts. Regular RDP fonts are drawn and encoded separately from images sent over the wire, but they have the drawback of not being very crisp and clear. Enabling smooth fonts means you get easier to read and clearer characters (ClearType), but they are sent as images, which may be slower. 322 | 323 | ![With Smooth Fonts](images/with_smooth_fonts.png "With Smooth Fonts") 324 | ![Without Smooth Fonts](images/without_smooth_fonts.png "Without Smooth Fonts") 325 | 326 | ## Desktop Composition 327 | 328 | Disabled by default, enable with +aero. This should not be confused with the desktop composition extension that redirects compositing calls for local rendering, a feature not supported by FreeRDP. This flag will only work in the few cases where compositing can be rendered over RemoteFX. As for now, this is only possible with Windows 7 SP1 on Hyper-V on Windows Server 2008 R2 SP1 with RemoteFX 3D. 329 | 330 | ## Full Window Dragging 331 | 332 | Disabled by default, enable with +window-drag. Dragging a window around is particularly intensive as it causes a lot of graphical updates (each time you move the window by one pixel, there is a large area of the screen that needs to be updated). To work around this problem, the server can draw the outline of the window as you drag it, and only draw the full window once you are done dragging it. 333 | 334 | ## Menu Animations 335 | 336 | Disabled by default, enable with +menu-anims. Just like window dragging, menu animations may cause a lot of successive graphical updates. Disabling it is a good idea. 337 | 338 | ## Themes 339 | 340 | Enabled by default, disable with -themes. Rich themes usually require operations with bitmaps, while a classic theme can often be drawn with simple and efficient operations using plain colors. Disabling themes is worth it if you can stand the look & feel. 341 | 342 | ![With Themes](images/with_themes.png "With Themes") 343 | ![Without Themes](images/without_themes.png "Without Themes") 344 | 345 | ## Wallpaper 346 | 347 | Enabled by default, disable with -wallpaper. The wallpaper may look pretty but it is a large image that compresses less efficiently than a plain color background. Disabling it reduce rendering time for the background, which is particularly noticeable at connection time and when minimizing windows. 348 | 349 | # Input 350 | 351 | Keyboard mapping is done on the remote end, so the local keyboard layout is ignored. Instead, a Windows keyboard layout id is provided at connection time to tell the server which keyboard layout to use. 352 | 353 | FreeRDP accepts either the numerical keyboard id or the full name of the corresponding keyboard layout: 354 | 355 | xfreerdp /v:rdp.contoso.com /kbd:US 356 | xfreerdp /v:rdp.contoso.com /kbd:0x409 357 | 358 | xfreerdp /v:rdp.contoso.com "/kbd:Canadian Multilingual Standard" 359 | xfreerdp /v:rdp.contoso.com /kbd:0x11009 360 | 361 | ![Language Bar](images/language_bar.png "Language Bar") 362 | 363 | If no keyboard layout is specified, FreeRDP selects a keyboard layout based on local system settings. The Microsoft RDP server only accepts the keyboard layout on session creation: if you are reconnecting to an existing session, you will need to log out first. 364 | 365 | The list of keyboard layout ids can be shown by using /kbd-list: 366 | 367 | xfreerdp /kbd-list 368 | 369 | Keyboard Layouts 370 | 0x00000401 Arabic (101) 371 | 0x00000402 Bulgarian 372 | 0x00000404 Chinese (Traditional) - US Keyboard 373 | 0x00000405 Czech 374 | 0x00000406 Danish 375 | 0x00000407 German 376 | 0x00000408 Greek 377 | 0x00000409 US 378 | .... 379 | 380 | One can search for his own keyboard layout by combining the above command with grep: 381 | 382 | xfreerdp /kbd-list | grep "Canadian" 383 | 0x00000C0C Canadian French (legacy) 384 | 0x00001009 Canadian French 385 | 0x00011009 Canadian Multilingual Standard 386 | 387 | ## Keyboard Layouts 388 | 389 | | Id | Name | 390 | |------------|----------------------------------------| 391 | | 0x00000401 | Arabic (101) | 392 | | 0x00000402 | Bulgarian | 393 | | 0x00000404 | Chinese (Traditional) - US Keyboard | 394 | | 0x00000405 | Czech | 395 | | 0x00000406 | Danish | 396 | | 0x00000407 | German | 397 | | 0x00000408 | Greek | 398 | | 0x00000409 | US | 399 | | 0x0000040A | Spanish | 400 | | 0x0000040B | Finnish | 401 | | 0x0000040C | French | 402 | | 0x0000040D | Hebrew | 403 | | 0x0000040E | Hungarian | 404 | | 0x0000040F | Icelandic | 405 | | 0x00000410 | Italian | 406 | | 0x00000411 | Japanese | 407 | | 0x00000412 | Korean | 408 | | 0x00000413 | Dutch | 409 | | 0x00000414 | Norwegian | 410 | | 0x00000415 | Polish (Programmers) | 411 | | 0x00000416 | Portuguese (Brazilian ABNT) | 412 | | 0x00000418 | Romanian | 413 | | 0x00000419 | Russian | 414 | | 0x0000041A | Croatian | 415 | | 0x0000041B | Slovak | 416 | | 0x0000041C | Albanian | 417 | | 0x0000041D | Swedish | 418 | | 0x0000041E | Thai Kedmanee | 419 | | 0x0000041F | Turkish Q | 420 | | 0x00000420 | Urdu | 421 | | 0x00000422 | Ukrainian | 422 | | 0x00000423 | Belarusian | 423 | | 0x00000424 | Slovenian | 424 | | 0x00000425 | Estonian | 425 | | 0x00000426 | Latvian | 426 | | 0x00000427 | Lithuanian IBM | 427 | | 0x00000429 | Farsi | 428 | | 0x0000042A | Vietnamese | 429 | | 0x0000042B | Armenian Eastern | 430 | | 0x0000042C | Azeri Latin | 431 | | 0x0000042F | FYRO Macedonian | 432 | | 0x00000437 | Georgian | 433 | | 0x00000438 | Faeroese | 434 | | 0x00000439 | Devanagari - INSCRIPT | 435 | | 0x0000043A | Maltese 47-key | 436 | | 0x0000043B | Norwegian with Sami | 437 | | 0x0000043F | Kazakh | 438 | | 0x00000440 | Kyrgyz Cyrillic | 439 | | 0x00000444 | Tatar | 440 | | 0x00000445 | Bengali | 441 | | 0x00000446 | Punjabi | 442 | | 0x00000447 | Gujarati | 443 | | 0x00000449 | Tamil | 444 | | 0x0000044A | Telugu | 445 | | 0x0000044B | Kannada | 446 | | 0x0000044C | Malayalam | 447 | | 0x0000044E | Marathi | 448 | | 0x00000450 | Mongolian Cyrillic | 449 | | 0x00000452 | United Kingdom Extended | 450 | | 0x0000045A | Syriac | 451 | | 0x00000461 | Nepali | 452 | | 0x00000463 | Pashto | 453 | | 0x00000465 | Divehi Phonetic | 454 | | 0x0000046E | Luxembourgish | 455 | | 0x00000481 | Maori | 456 | | 0x00000804 | Chinese (Simplified) - US Keyboard | 457 | | 0x00000807 | Swiss German | 458 | | 0x00000809 | United Kingdom | 459 | | 0x0000080A | Latin American | 460 | | 0x0000080C | Belgian French | 461 | | 0x00000813 | Belgian (Period) | 462 | | 0x00000816 | Portuguese | 463 | | 0x0000081A | Serbian (Latin) | 464 | | 0x0000082C | Azeri Cyrillic | 465 | | 0x0000083B | Swedish with Sami | 466 | | 0x00000843 | Uzbek Cyrillic | 467 | | 0x0000085D | Inuktitut Latin | 468 | | 0x00000C0C | Canadian French (legacy) | 469 | | 0x00000C1A | Serbian (Cyrillic) | 470 | | 0x00001009 | Canadian French | 471 | | 0x0000100C | Swiss French | 472 | | 0x0000141A | Bosnian | 473 | | 0x00001809 | Irish | 474 | | 0x0000201A | Bosnian Cyrillic | 475 | 476 | ## Keyboard Layout Variants 477 | 478 | | Id | Name | 479 | |------------|----------------------------------------| 480 | | 0x00010401 | Arabic (102) | 481 | | 0x00010402 | Bulgarian (Latin) | 482 | | 0x00010405 | Czech (QWERTY) | 483 | | 0x00010407 | German (IBM) | 484 | | 0x00010408 | Greek (220) | 485 | | 0x00010409 | United States-Dvorak | 486 | | 0x0001040A | Spanish Variation | 487 | | 0x0001040E | Hungarian 101-key | 488 | | 0x00010410 | Italian (142) | 489 | | 0x00010415 | Polish (214) | 490 | | 0x00010416 | Portuguese (Brazilian ABNT2) | 491 | | 0x00010419 | Russian (Typewriter) | 492 | | 0x0001041B | Slovak (QWERTY) | 493 | | 0x0001041E | Thai Pattachote | 494 | | 0x0001041F | Turkish F | 495 | | 0x00010426 | Latvian (QWERTY) | 496 | | 0x00010427 | Lithuanian | 497 | | 0x0001042B | Armenian Western | 498 | | 0x00010439 | Hindi Traditional | 499 | | 0x0001043A | Maltese 48-key | 500 | | 0x0001043B | Sami Extended Norway | 501 | | 0x00010445 | Bengali (Inscript) | 502 | | 0x0001045A | Syriac Phonetic | 503 | | 0x00010465 | Divehi Typewriter | 504 | | 0x0001080C | Belgian (Comma) | 505 | | 0x0001083B | Finnish with Sami | 506 | | 0x00011009 | Canadian Multilingual Standard | 507 | | 0x00011809 | Gaelic | 508 | | 0x00020401 | Arabic (102) AZERTY | 509 | | 0x00020405 | Czech Programmers | 510 | | 0x00020408 | Greek (319) | 511 | | 0x00020409 | United States-International | 512 | | 0x0002041E | Thai Kedmanee (non-ShiftLock) | 513 | | 0x0002083B | Sami Extended Finland-Sweden | 514 | | 0x00030408 | Greek (220) Latin | 515 | | 0x00030409 | United States-Dvorak for left hand | 516 | | 0x0003041E | Thai Pattachote (non-ShiftLock) | 517 | | 0x00040408 | Greek (319) Latin | 518 | | 0x00040409 | United States-Dvorak for right hand | 519 | | 0x00050408 | Greek Latin | 520 | | 0x00050409 | US English Table for IBM Arabic 238_L | 521 | | 0x00060408 | Greek Polytonic | 522 | | 0xB0000407 | German Neo | 523 | 524 | ## Keyboard Input Method Editors (IMEs) 525 | 526 | | Id | Name | 527 | |------------|----------------------------------------| 528 | | 0xE0010404 | Chinese (Traditional) - Phonetic | 529 | | 0xE0010411 | Japanese Input System (MS-IME2002) | 530 | | 0xE0010412 | Korean Input System (IME 2000) | 531 | | 0xE0010804 | Chinese (Simplified) - QuanPin | 532 | | 0xE0020404 | Chinese (Traditional) - ChangJie | 533 | | 0xE0020804 | Chinese (Simplified) - ShuangPin | 534 | | 0xE0030404 | Chinese (Traditional) - Quick | 535 | | 0xE0030804 | Chinese (Simplified) - ZhengMa | 536 | | 0xE0040404 | Chinese (Traditional) - Big5 Code | 537 | | 0xE0050404 | Chinese (Traditional) - Array | 538 | | 0xE0050804 | Chinese (Simplified) - NeiMa | 539 | | 0xE0060404 | Chinese (Traditional) - DaYi | 540 | | 0xE0070404 | Chinese (Traditional) - Unicode | 541 | | 0xE0080404 | Chinese (Traditional) - New Phonetic | 542 | | 0xE0090404 | Chinese (Traditional) - New ChangJie | 543 | | 0xE00E0804 | Chinese (Traditional) - Microsoft Pinyin IME 3.0 | 544 | | 0xE00F0404 | Chinese (Traditional) - Alphanumeric | 545 | 546 | # Redirection 547 | 548 | ## Drive Redirection 549 | 550 | To redirect all drives, use /drives: 551 | 552 | xfreerdp /v:rdp.contoso.com /drives 553 | 554 | On Windows, each drive has a letter and is redirected individually. On Linux, the root directory (/) is redirected, which is equivalent to redirecting all drives. 555 | 556 | To redirect the user home directory as a drive, use /home-drive: 557 | 558 | xfreerdp /v:rdp.contoso.com /home-drive 559 | 560 | This is convenient if the user "JohnDoe" wants to redirect only "/home/JohnDoe" instead of the root directory ("/"). 561 | 562 | ## Serial Redirection 563 | 564 | To redirect a serial device, you must first identify the corresponding device file. If you are using a USB to serial adapter, the device usually shows up as /dev/ttyUSB0. 565 | 566 | In most cases, the device representing the serial device will not be usable with user permissions. You can either chown or chmod the device or do it cleanly with udev rules. 567 | 568 | xfreerdp /serial:COM3,/dev/ttyUSB0 /v:rdp.contoso.com 569 | 570 | It might be confusing at first, but the redirected serial ports will not appear in the device manager. Instead, open a command prompt and type: 571 | 572 | >change port /query 573 | AUX = \DosDevices\COM1 574 | COM1 = \Device\Serial0 575 | COM2 = \Device\Serial1 576 | COM3 = \Device\RdpDrPort\;COM3:2\tsclient\COM3 577 | GLOBALROOT = 578 | 579 | In this above listing, /dev/ttyUSB0 is redirected as COM3. 580 | 581 | You need to manually map the remote COM port to a local COM port: 582 | 583 | net use COMx: \\tsclient\COMy 584 | 585 | Where x is a COM port available on the server and y is a COM port available on the client. 586 | 587 | ![FreeRDP Serial Redirection](images/freerdp_serial_redirection.png "FreeRDP Serial Redirection") 588 | 589 | ## Parallel Redirection 590 | 591 | To be expanded. 592 | 593 | ## Smartcard Redirection 594 | 595 | To be expanded. 596 | 597 | ## Printer Redirection 598 | 599 | To redirect all printers, use /printer: 600 | 601 | xfreerdp /v:rdp.contoso.com /printer 602 | 603 | On Linux and UNIX systems, CUPS is the printing backend used. An easy way to test printing without a physical printer is to install [CUPS-PDF](http://www.cups-pdf.de/ ""), a simple CUPS pdf printer. 604 | 605 | Under normal circumstances, if your printer is properly configured with CUPS on the client, it should be picked up by FreeRDP and redirected properly. If you are looking for recommendations on a printer which works well with major operating systems (Windows, Linux, Mac OS X) the HP LaserJet Pro P1606dn is a good choice. 606 | 607 | ![FreeRDP Printer Redirection](images/freerdp_print_cups_pdf.png "FreeRDP Printer Redirection") 608 | 609 | ## Clipboard redirection 610 | 611 | To enable clipboard redirection, use /clipboard: 612 | 613 | xfreerdp /v:rdp.contoso.com /clipboard 614 | 615 | While clipboard redirection is supported in remote desktop mode, it is not yet supported with RemoteApp due to certain technical challenges. 616 | 617 | ## Audio Playback 618 | 619 | To enable sound redirection, use /sound: 620 | 621 | xfreerdp /v:rdp.contoso.com /sound 622 | 623 | To select a specific sound subsystem, use the sys:<subsystem> parameter: 624 | 625 | xfreerdp /v:rdp.contoso.com /sound:sys:alsa 626 | xfreerdp /v:rdp.contoso.com /sound:sys:pulse 627 | 628 | If you experience occasional sound skipping, you may try adjusting the sound latency with the latency:<milliseconds> parameter: 629 | 630 | xfreerdp /v:rdp.contoso.com /sound:latency:400 631 | 632 | A short latency will give better audio and video synchronization but will have a shorter buffering time, which makes sound skipping more likely. 633 | 634 | ## Audio Recording 635 | 636 | To enable audio input (recording), use /microphone: 637 | 638 | xfreerdp /v:rdp.contoso.com /microphone 639 | 640 | To select a specific sound subsystem, use the sys:<subsystem> parameter: 641 | 642 | xfreerdp /v:rdp.contoso.com /microphone:sys:alsa 643 | xfreerdp /v:rdp.contoso.com /microphone:sys:pulse 644 | 645 | ## Multitouch Input 646 | 647 | Multitouch redirection was introduced in RDP8 and is therefore only supported with Windows 8 and Windows Server 2012 servers. If you have a multitouch display, you can enable true multitouch redirection using /multitouch: 648 | 649 | xfreerdp /v:rdp.contoso.com /multitouch 650 | 651 | RDP8 multitouch is meant for *direct* touch devices like multitouch displays and not *dependent* touch devices like multitouch trackpads. 652 | 653 | ![FreeRDP Multitouch Input](images/freerdp_multitouch.png "FreeRDP Multitouch Input") 654 | 655 | # Registry Settings 656 | 657 | FreeRDP supports configuration through registry keys using the WinPR Registry API. On Windows, the native Windows registry is used. On other platforms, WinPR uses a simple .reg file. 658 | 659 | ![FreeRDP Windows Registry Settings](images/windows_registry.png "FreeRDP Windows Registry Settings") 660 | 661 | Most settings are found under [HKEY_LOCAL_MACHINE\\Software\\FreeRDP] and [HKEY_LOCAL_MACHINE\\Software\\WinPR]. On Windows, use regedit.exe to edit the registry settings. On other operating systems, WinPR looks for a file called /etc/winpr/HKLM.reg. This file is in the .reg file format and can be edited manually with a text editor. On Windows, .reg files can be obtained by exporting a section of the registry in regedit.exe. To do so, right-click the key in the left pane and select Export. The resulting .reg file is shown in the above screenshot. This textual file can then serve as a template for non-Windows usage. 662 | 663 | On non-Windows systems, the /etc/winpr folder usually needs to be created manually. It is recommended to restrict permissions to this folder due to the sensitive nature of certain configuration settings. Current FreeRDP registry settings are all under HKEY_LOCAL_MACHINE, the registry hive meant for system-wide configuration. In the future, user-specific settings may be added under HKEY_LOCAL_USERS, but this has not been done yet. 664 | 665 | sudo mkdir /etc/winpr 666 | sudo nano /etc/winpr/HKLM.reg 667 | 668 | ![FreeRDP Linux Registry Settings](images/linux_registry.png "FreeRDP Linux Registry Settings") 669 | 670 | ## .reg File Format 671 | 672 | The .reg file format is normally used for exporting and exporting registry settings, and is well described in the [Microsoft Knowledge Base Article 310516](http://support.microsoft.com/kb/310516 ""). It begins with a line containing the file format name and version number, followed by an empty line: 673 | 674 | Windows Registry Editor Version 5.00 675 | 676 | Registry "keys" correspond to the folders in the registry hierarchy. A key can have subkeys or values. Each value in the registry is strongly typed. Common types are REG_DWORD, REG_BINARY, and REG_SZ. 677 | 678 | Here is a sample .reg file containing a test key with a subkey, and values of type REG_DWORD, REG_BINARY and REG_SZ: 679 | 680 | Windows Registry Editor Version 5.00 681 | 682 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Test] 683 | "DwordValue"=dword:0000007b 684 | "StringValue"="this is a string" 685 | 686 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Test\Subkey] 687 | "BinaryValue"=hex:aa,bb,cc,dd,ee,ff 688 | 689 | ### REG_DWORD (Integer) 690 | 691 | REG_DWORD is a double word, or a 32-bit unsigned integer. It is used for numbers and also for boolean values. If the value is to be interpreted as boolean, 0 is considered FALSE and non-zero is considered TRUE. REG_DWORD values are formatted as 8 hexadecimal characters, so make sure to write a value in base 16 and not in base 10 when editing manually. In this case, 0000007b is hexadecimal for 123 in decimal. 692 | 693 | ### REG_SZ (String) 694 | 695 | REG_SZ is a text string. Windows exports unicode strings as REG_BINARY. 696 | 697 | ### REG_BINARY (Binary Data) 698 | 699 | REG_BINARY is either raw data or a unicode string. It is exported as a list of hexadecimal values separated by commas. 700 | 701 | ## Client Settings 702 | 703 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Client] 704 | 705 | | Value | Type | Description | 706 | |-----------------------------|---------|-----------------------------------------------------| 707 | | DesktopWidth | Integer | Default desktop width (/w) | 708 | | DesktopHeight | Integer | Default desktop height (/h) | 709 | | Fullscreen | Boolean | Toggle Fullscreen mode (/f) | 710 | | ColorDepth | Integer | Default color depth (/bpp) | 711 | | KeyboardType | Integer | Default keyboard type (/kbd-type) | 712 | | KeyboardSubType | Integer | Default keyboard subtype (/kbd-subtype) | 713 | | KeyboardFunctionKeys | Integer | Default keyboard function keys (/kbd-fn-key) | 714 | | KeyboardLayout | Integer | Default keyboard layout id (/kbd) | 715 | | ExtSecurity | Boolean | Extended security (/sec-ext) | 716 | | NlaSecurity | Boolean | Toggle NLA security (/sec-nla) | 717 | | TlsSecurity | Boolean | Toggle TLS security (/sec-tls) | 718 | | RdpSecurity | Boolean | Toggle Standard RDP security (/sec-rdp) | 719 | | MstscCookieMode | Boolean | Toggle connection cookie truncation to 9 characters | 720 | | CookieMaxLength | Integer | Maximum connection cookie length for truncation | 721 | | BitmapCache | Boolean | Toggle bitmap cache (/bitmap-cache) | 722 | | OffscreenBitmapCache | Boolean | Toggle offscreen bitmap cache (/offscreen-cache) | 723 | | OffscreenBitmapCacheSize | Integer | Offscreen bitmap cache size | 724 | | OffscreenBitmapCacheEntries | Integer | Offscreen bitmap cache entry count | 725 | | GlyphCache | Boolean | Toggle glyph cache (/glyph-cache) | 726 | 727 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Client\BitmapCacheV2] 728 | 729 | | Value | Type | Description | 730 | |-----------------------------|---------|----------------------------------------------| 731 | | NumCells | Integer | Number of cells in bitmap cache | 732 | | Cell0NumEntries | Integer | Number of entries in bitmap cache cell 0 | 733 | | Cell0Persistent | Boolean | Toggle persistence for bitmap cache cell 0 | 734 | | Cell1NumEntries | Integer | Number of entries in bitmap cache cell 1 | 735 | | Cell1Persistent | Boolean | Toggle persistence for bitmap cache cell 1 | 736 | | Cell2NumEntries | Integer | Number of entries in bitmap cache cell 2 | 737 | | Cell2Persistent | Boolean | Toggle persistence for bitmap cache cell 2 | 738 | | Cell3NumEntries | Integer | Number of entries in bitmap cache cell 3 | 739 | | Cell3Persistent | Boolean | Toggle persistence for bitmap cache cell 3 | 740 | | Cell4NumEntries | Integer | Number of entries in bitmap cache cell 4 | 741 | | Cell4Persistent | Boolean | Toggle persistence for bitmap cache cell 4 | 742 | | AllowCacheWaitingList | Boolean | Allow bitmap cache waiting list | 743 | 744 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Client\GlyphCache] 745 | 746 | | Value | Type | Description | 747 | |-----------------------------|---------|----------------------------------------------| 748 | | SupportLevel | Integer | Glyph cache support level | 749 | | Cache0NumEntries | Integer | Number of entries in glyph cache cell 0 | 750 | | Cache0MaxCellSize | Integer | Glyph cache cell 0 maximum size | 751 | | Cache1NumEntries | Integer | Number of entries in glyph cache cell 1 | 752 | | Cache1MaxCellSize | Integer | Glyph cache cell 1 maximum size | 753 | | Cache2NumEntries | Integer | Number of entries in glyph cache cell 2 | 754 | | Cache2MaxCellSize | Integer | Glyph cache cell 2 maximum size | 755 | | Cache3NumEntries | Integer | Number of entries in glyph cache cell 3 | 756 | | Cache3MaxCellSize | Integer | Glyph cache cell 3 maximum size | 757 | | Cache4NumEntries | Integer | Number of entries in glyph cache cell 4 | 758 | | Cache4MaxCellSize | Integer | Glyph cache cell 4 maximum size | 759 | | Cache5NumEntries | Integer | Number of entries in glyph cache cell 5 | 760 | | Cache5MaxCellSize | Integer | Glyph cache cell 5 maximum size | 761 | | Cache6NumEntries | Integer | Number of entries in glyph cache cell 6 | 762 | | Cache6MaxCellSize | Integer | Glyph cache cell 6 maximum size | 763 | | Cache7NumEntries | Integer | Number of entries in glyph cache cell 7 | 764 | | Cache7MaxCellSize | Integer | Glyph cache cell 7 maximum size | 765 | | Cache8NumEntries | Integer | Number of entries in glyph cache cell 8 | 766 | | Cache8MaxCellSize | Integer | Glyph cache cell 8 maximum size | 767 | | Cache9NumEntries | Integer | Number of entries in glyph cache cell 9 | 768 | | Cache9MaxCellSize | Integer | Glyph cache cell 9 maximum size | 769 | | FragCacheNumEntries | Integer | Number of entries in glyph fragment cache | 770 | | FragCacheMaxCellSize | Integer | Glyph fragment cache cell maximum size | 771 | 772 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Client\PointerCache] 773 | 774 | | Value | Type | Description | 775 | |-----------------------------|---------|---------------------------------------------| 776 | | LargePointer | Boolean | Large pointer support | 777 | | ColorPointer | Boolean | Color pointer support | 778 | | PointerCacheSize | Integer | Pointer cache size | 779 | 780 | ## Server Settings 781 | 782 | [HKEY_LOCAL_MACHINE\SOFTWARE\FreeRDP\Server] 783 | 784 | | Value | Type | Description | 785 | |----------------------------|---------|----------------------------------------------| 786 | | ExtSecurity | Boolean | Extended security | 787 | | NlaSecurity | Boolean | Toggle NLA security | 788 | | TlsSecurity | Boolean | Toggle TLS security | 789 | | RdpSecurity | Boolean | Toggle Standard RDP security | 790 | | CertificateFile | String | Absolute path to x509 certificate file | 791 | | PrivateKeyFile | String | Absolute path to x509 key file | 792 | -------------------------------------------------------------------------------- /User/FreeRDP-User-Manual.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/FreeRDP-User-Manual.pdf -------------------------------------------------------------------------------- /User/images/freerdp_multitouch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/freerdp_multitouch.png -------------------------------------------------------------------------------- /User/images/freerdp_print_cups_pdf.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/freerdp_print_cups_pdf.png -------------------------------------------------------------------------------- /User/images/freerdp_serial_redirection.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/freerdp_serial_redirection.png -------------------------------------------------------------------------------- /User/images/language_bar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/language_bar.png -------------------------------------------------------------------------------- /User/images/linux_registry.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/linux_registry.png -------------------------------------------------------------------------------- /User/images/mstsc_help.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/mstsc_help.png -------------------------------------------------------------------------------- /User/images/windows_registry.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/windows_registry.png -------------------------------------------------------------------------------- /User/images/winlogon_gui.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/winlogon_gui.png -------------------------------------------------------------------------------- /User/images/with_smooth_fonts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/with_smooth_fonts.png -------------------------------------------------------------------------------- /User/images/with_themes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/with_themes.png -------------------------------------------------------------------------------- /User/images/without_smooth_fonts.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/without_smooth_fonts.png -------------------------------------------------------------------------------- /User/images/without_themes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/awakecoding/FreeRDP-Manuals/88c0158c896565214e6b145f67e95efe8dee883f/User/images/without_themes.png -------------------------------------------------------------------------------- /gen.pl: -------------------------------------------------------------------------------- 1 | #!/usr/bin/perl 2 | 3 | # requires pandoc 1.10+ 4 | 5 | sub pandoc_generate_pdf 6 | { 7 | ($DIR, $DOC) = @_; 8 | 9 | chdir($DIR); 10 | 11 | print "Generating $DOC PDF...\n"; 12 | 13 | my $CMD = "pandoc $DOC.markdown " . 14 | " -f markdown+pipe_tables+fenced_code_blocks+definition_lists " . 15 | "--smart --normalize --number-sections --section-divs --toc " . 16 | "--variable=links-as-notes:true --variable=documentclass:report --to=latex " . 17 | "--variable=lang:english --variable=urlcolor:black --variable=linkcolor:black " . 18 | " --variable=verbatim-in-note:true " . 19 | "--output=$DOC.pdf"; 20 | 21 | print "$CMD\n"; 22 | 23 | system($CMD); 24 | 25 | chdir(".."); 26 | 27 | print "Done!\n"; 28 | } 29 | 30 | $USER_DIR = "User"; 31 | $USER_DOC = "FreeRDP-User-Manual"; 32 | 33 | $DEV_DIR = "Developer"; 34 | $DEV_DOC = "FreeRDP-Developer-Manual"; 35 | 36 | $CFG_DIR = "Configuration"; 37 | $CFG_DOC = "FreeRDP-Configuration-Manual"; 38 | 39 | $TEST_DIR = "Testing"; 40 | $TEST_DOC = "FreeRDP-Testing-Manual"; 41 | 42 | @DIRS = (); 43 | @DOCS = (); 44 | 45 | foreach $i (0 .. $#ARGV) { 46 | if ($ARGV[$i] =~ m/^user$/) { 47 | push(@DIRS, $USER_DIR); 48 | push(@DOCS, $USER_DOC); 49 | } elsif ($ARGV[$i] =~ m/^dev$/) { 50 | push(@DIRS, $DEV_DIR); 51 | push(@DOCS, $DEV_DOC); 52 | } elsif ($ARGV[$i] =~ m/^cfg$/) { 53 | push(@DIRS, $CFG_DIR); 54 | push(@DOCS, $CFG_DOC); 55 | } elsif ($ARGV[$i] =~ m/^test$/) { 56 | push(@DIRS, $TEST_DIR); 57 | push(@DOCS, $TEST_DOC); 58 | } 59 | } 60 | 61 | if ($#ARGV eq -1) { 62 | @DIRS = ($USER_DIR, $DEV_DIR, $CFG_DIR, $TEST_DIR); 63 | @DOCS = ($USER_DOC, $DEV_DOC, $CFG_DOC, $TEST_DOC); 64 | } 65 | 66 | foreach (@DOCS) { 67 | $DIR = shift(@DIRS); 68 | pandoc_generate_pdf($DIR, $_,); 69 | } 70 | 71 | --------------------------------------------------------------------------------