diff --git a/docs/man/Makefile.am b/docs/man/Makefile.am index 8dbd7142..48720ee8 100644 --- a/docs/man/Makefile.am +++ b/docs/man/Makefile.am @@ -8,6 +8,7 @@ man_MANS = \ xrdp-dis.1 \ sesman.ini.5 \ xrdp.ini.5 \ + xrdp-km.toml.5 \ xrdp.8 \ xrdp-chansrv.8 \ xrdp-genkeymap.8 \ diff --git a/docs/man/xrdp-genkeymap.8.in b/docs/man/xrdp-genkeymap.8.in index eb939979..5e4ea63c 100644 --- a/docs/man/xrdp-genkeymap.8.in +++ b/docs/man/xrdp-genkeymap.8.in @@ -9,48 +9,44 @@ .SH "SYNTAX" .B xrdp\-genkeymap -.I file +.I [ options ] file .SH "DESCRIPTION" -\fBxrdp\-genkeymap\fR extracts the key map used by the currently running X session to generated a mapping from Remote Desktop Protocol (RDP) key codes to X keysyms and Unicode code points. +\fBxrdp\-genkeymap\fR extracts the current key map from the X server +X session to generate a mapping from Remote Desktop Protocol (RDP) +scan codes to X keysyms and Unicode code points. + +Before running this utility, make sure the keymap is correct, by issuing +the correct \fIsetxkbmap\fP command(s). .SH OPTIONS .TP -.I outfile +.B -k 'keycode_set' +Inform \fBxrdp\-genkeymap\fR of the keycode set in operation (evdev or +base), so that the correct scan code to keycode mapping table is selected +to generate the keymap. + +If you omit this option, the XKB extension is asked to provide the +name of the keycode set. + +.TP +.B -c 'comment' +Adds a comment to the top of the generated file. + +This option may be repeated more than once to add multiple comments to +the top of the file. +.TP +.B outfile The key map information is stored in the file named \fIoutfile\fP. .SH "FILES" .TP -.I @sysconfdir@/xrdp/km-XXXXXXXX.ini -Files containing the keyboard mapping for language \fIXXXXXXXX\fP, which is a 8 digit hexadecimal number identifying the country and language code. -.RS 8 -.TP -.B 00000405 -cs Czech -.TP -.B 00000407 -de German -.TP -.B 00000409 -en-us US English -.TP -.B 0000040c -fr French -.TP -.B 00000410 -it Italian -.TP -.B 00000416 -br Portuguese (Brazil) -.TP -.B 00000419 -ru Russian -.TP -.B 0000041d -se Swedish -.TP -.B 00000809 -en-uk UK English +.I @sysconfdir@/xrdp/km-XXXXXXXX.toml +Files containing the keyboard mapping for country and language \fIXXXXXXXX\fP. +\fIXXXXXXXX\fP is a 8 digit hexadecimal number, representing the \fIinput +locale identifier\fP. + +The input locale identifier is passed from the RDP client when it connects. .RE .SH "AUTHORS" @@ -60,8 +56,15 @@ Simone Fedele .SH "SEE ALSO" .BR xrdp (8), +.BR xrdp-km.toml (5), .BR setxkbmap (1), .BR unicode (7) + +.PP +Input locale identifiers on the +.UR https://go.microsoft.com/fwlink/?LinkId=202824 +Microsoft website +.UE .PP Description of Keyboard Input mapping on the .UR https://github.com/FreeRDP/FreeRDP/wiki/Keyboard diff --git a/docs/man/xrdp-km.toml.5.in b/docs/man/xrdp-km.toml.5.in new file mode 100644 index 00000000..a9dbc432 --- /dev/null +++ b/docs/man/xrdp-km.toml.5.in @@ -0,0 +1,129 @@ +.\" +.TH "xrdp-km.toml" "5" "@PACKAGE_VERSION@" "xrdp team" "" +.SH "NAME" +\fBxrdp-km.toml\fR \- \fBxrdp\fP key mapping file + +.SH "DESCRIPTION" +Key mapping files are located at \fB@sysconfdir@/xrdp/km-XXXXXXXX.toml\fP +where \fBXXXXXXXX\fP is the input locale identifier sent by the RDP client. + +The key mapping files are used to translate RDP scan codes into one of +the following forms:- +.TP +.B X11 KeySyms +These are used when \fBxrdp\fP connects to a VNC server. +.TP +.B Unicode characters +These are used on the \fBxrdp\fP login screen. +.RE +.PP +Each keymap file consists of several sections. Each section starts with +the section name in square brackets, followed by a list of +\fIparameter\fR=\fIvalue\fR lines. + +.SH "SECTIONS" +The following sections are recognized: +.TP +\fB[Globals]\fR +Global configuration + +.TP +\fB[noshift]\fR +Key mappings if no modifier keys (i.e. shift, alt gr, caps lock) are down. +.TP +\fB[shift]\fR +Key mappings if the shift key is down. +.TP +\fB[altgr]\fR +Key mappings if the alt gr key is down. +.TP +\fB[shiftaltgr]\fR +Key mappings if the shift and alt gr keys are down. +.TP +\fB[capslock]\fR +Key mappings if the caps lock key is down. +.TP +\fB[shiftcapslock]\fR +Key mappings if the caps lock and shift keys are down. +.TP +\fB[shiftcapslockaltgr]\fR +Key mappings if the shift, caps lock and alt gr keys are down. +.TP +\fB[numlock]\fR +Key mappings if the numlock key is down. + +.LP +All parameters and values are case +insensitive, and are described in detail below. If any parameter is +specified more than once, the last entry will be used. Options specified +outside their proper section will be \fIignored\fR. + +.SH "GLOBALS Section" +Following parameters can be used in the \fB[Globals]\fR section. + +.TP +\fBVersion\fR=\fInumber\fR +Version of the file format in use. +Can be used to check for file format mis-matches when a file is loaded. +.RE + +.SH "Keymap Sections" +All other sections contain lines formatted in one of the following +ways:- + +.TP += +.TP +=: +.RE + +Each line may also be followed by a comment (preceded by '#') which +contains more information about the key, for example a KeySym string. + +.TP +.B scancode +A \fBscancode\fP is an RDP scancode received from the client. These +correspond to Windows "Scan Code Set 1" scan codes, and can be displayed +in Windows by using an appropriate utility. + +The \fBscancode\fP is in one of these two forms:- + +.RS 8 +.TP +.B +Standard scancodes. For example, '1C' refers to the enter key. +These are 'key down' scancodes, and so are always between 00 and 7F. +.TP +.B E0_ +Extended scancodes. For example, 'E0_1C' refers to the enter key on the numeric keypad. +.RE + +.TP +.B KeySymNum +A decimal number representing an X11 KeySym + +.TP +.B unicode-char +A string of the format \fBU+XXXX\fP \fBU+XXXXX\fP,, \fBU+XXXXX\fP, +where \fBX\fP is a hexadecimal digit. +.RE + +.SH "Limitations" +This file format has the following limitations. +.IP \(bu +Not all combinations of shift keys are stored in the file. For example, +at present there is no section for shift and numlock combined. +.IP \(bu +Modifier keys, other than the ones supported above, are not supported. + +.SH "SEE ALSO" +.BR xrdp-genkeymap (8) + +.PP +Scancode mappings for most keyboards at +.UR https://kbdlayout.info +.UE + +For more info on \fBxrdp\fR see +.UR @xrdphomeurl@ +.UE diff --git a/genkeymap/readme.txt b/genkeymap/readme.txt index a5bc1b85..7fa0e097 100644 --- a/genkeymap/readme.txt +++ b/genkeymap/readme.txt @@ -10,47 +10,10 @@ km-xxxxxxxx.toml where the xxxxxxxx is replaced by the hex number of the layout of interest. -The files are TOML compatible, with 10 sections; +The contents of the files are documented in xrdp-km.toml(5) -[General], [noshift], [shift], [altgr], [shiftaltgr], [capslock], -[capslockaltgr], [shiftcapslock], [shiftcapslockaltgr], [numlock] - -The [General] section contains information about the file. All other -sections contain key mappings corresponding to the state of the modifier -keys when the key is pressed. - -An example line looks like; - -="[:]" # comment - -RDP scancode ------------- -The RDP scancode is the code received from the RDP client for each -key. RDP scancodes are more-or-less the same as Windows scancodes, -or "Scan Code Set 1" key-down values. - -Example scancodes might be '1C' for the enter key on most European -keyboards, or 'E0 1C' for the number pad enter key. - -A good website to consult for scancodes for a wide range of keyboards is -https://kbdlayout.info/ - -KeySym ------- -The KeySym is a value used by the X server as an abstraction of the -engraving on the key being pressed. It is needed to interact with the -VNC server. - -Unicode -------- -Keys which generate a character when pressed have this value added. -This is used by the xrdp login screen. - -Comment -------- -For generated keymap files, the comment is the name of the X11 KeySym -for the key. This makes it a lot easier to see what is going on in -the file. +See also xrdp-genkeymap(8) which describes the utility used to +generate these files. Creating a new file ------------------- @@ -58,24 +21,29 @@ Creating a new file To create a new file:- 1) Start an X server 2) Use the 'setxkbmap' command to get the keyboard configured - for the X server. Currently this has to use the 'evdev' rules so - that xrdp and the X server agree on the low-level X11 keycodes to - be used for the keys. + for the X server. 3) Run the 'xrdp-genkeymap' command to extract the keyboard mappings - Example: ./xrdp-genkeymap /etc/xrdp/km-00000409.toml + Example: ./xrdp-genkeymap ./km-00000409.toml -Note: You need to have enough rights to be able to write to the -/etc/xrdp directory. - -Alternatively, create the keymap file in a directory of your choice, then -copy or move it over to /etc/xrdp using sudo/su. +4) Copy the generated file to /etc/xrdp/ Using the X server of your current session may not be a good idea, as session and window managers can interfere with key bindings. A good option is to use an 'Xvfb' dummy X server to do this. -See also the dump_keymaps.sh script which auto-generates many keymap -files for the xrdp distribution. Consider adding your keyboard into this -list. +Getting a file added to xrdp +---------------------------- + +The file dump-keymaps.sh in this directory is used to auto-generate +all keymap files. It runs on Linux currently, but will generate +keymap files suitable for any xrdp platform. + +1) Add a line towards the end of this file which causes your mapping to + be generated. Use the other lines in this file as a guide. +2) Run the dump-keymaps.sh script to generate a new file in + instfiles/ +3) Add your mapping to the list in instfiless/Makefile.am +4) Submit a pull request to the project containing the above three + changes.