modules.d/10i18n/README

   1 dracut i18n module
   2 ------------------
   3
   4 INDEX
   5
   6 0. Introduction
   7 1. Hostonly vs Generic
   8 2. Configuration
   9    2.1. Variables
  10    2.2. Setting up mappings
  11    2.3. Additional settings
  12 3. Kernel parameters
  13
  14 ~
  15
  16 0. Introduction
  17
  18 i18n module provides internationalization for initramfs at runtime.  It
  19 is intended to be generic across different GNU/Linux distributions.
  20
  21 i18n and keyboard settings are stored in different files among
  22 distributions.  To deal with it avoiding hardcoding those differences in
  23 the installation script we handle it by mappings between variables used
  24 by dracut and the ones in the system.  Package maintainer is expected to
  25 create those for his/her distribution and it's appreciated to share it
  26 with us, so we can include it in source package.
  27
  28
  29 1. Hostonly vs Generic
  30
  31 If you invoke dracut with '-H' option, i18n module install script will
  32 gather variables values from your configuration files using mappings
  33 provided in "/etc/dracut.conf.d/<foo>.conf".  Those variables will be
  34 put in "etc/vconsole.conf" and "etc/locale.conf" files inside initramfs
  35 image. Next it will install only declared font, keymaps and so.
  36
  37 When building generic image (dracut without '-H' option), install script
  38 copies all content of directories: consolefonts, consoletrans, unimaps
  39 and keymaps to image.  Take into account that's about 4 MiB.
  40
  41
  42 2. Configuration
  43
  44 2.1. Variables
  45
  46 The following variables are used by i18n install script and at initramfs
  47 runtime:
  48
  49     KEYMAP - keyboard translation table loaded by loadkeys
  50     KEYTABLE - base name for keyboard translation table; if UNICODE is
  51     true, Unicode version will be loaded. Overrides KEYMAP.
  52     EXT_KEYMAPS - list of extra keymaps to bo loaded (sep. by space)
  53     UNICODE - boolean, indicating UTF-8 mode
  54     FONT - console font
  55     FONT_MAP - see description of '-m' parameter in setfont manual
  56     FONT_UNIMAP - see description of '-u' parameter in setfont manual
  57
  58 The following are appended to EXT_KEYMAPS only during build time:
  59
  60     UNIKEYMAP
  61     GRP_TOGGLE
  62
  63 They were used in 10redhat-i18n module, but not sure of its purpose.
  64 I'm leaving it in case...  The following are taken from the environment:
  65
  66     LANG
  67     LC_ALL
  68
  69 If UNICODE variable is not provided, script indicates if UTF-8 should be
  70 used on the basis of LANG value (if it ends with ".utf8" or similar).
  71
  72
  73 2.2. Setting up mappings
  74
  75 Mappings between variables listed in 2.1. and the ones spread around
  76 your system are set up in /etc/dracut.conf.d/<foo>.conf.  You need to
  77 assign mappings to i18n_vars.  Here's an example:
  78
  79 i18n_vars="/etc/conf.d/keymaps:KEYMAP,EXTENDED_KEYMAPS-EXT_KEYMAPS /etc/conf.d/consolefont:CONSOLEFONT-FONT,CONSOLETRANSLATION-FONT_MAP /etc/rc.conf:UNICODE"
  80
  81 First we've got name of file in host file system tree.  After colon
  82 there's mapping: <from>-<to>.  If both variables have the same name you
  83 can enter just a single, but it's important to specify it!  The module
  84 will source only variables you've listed.
  85
  86 Below there's detailed description in BNF:
  87
  88 <list> ::= <element> | <element> " " <list>
  89 <element> ::= <conf-file-name> ":" <map-list>
  90 <map-list> ::= <mapping> | <mapping> "," <map-list>
  91 <mapping> ::= <src-var> "-" <dst-var> | <src-var>
  92
  93 We assume no whitespace are allowed between symbols.
  94 <conf-file-name> is a file holding <src-var> in your system.
  95 <src-var> is a variable holding value of meaning the same as <dst-var>.
  96 <dst-var> is a variable which will be set up inside initramfs.
  97 If <dst-var> has the same name as <src-var> we can omit <dst-var>.
  98
  99 Example:
 100 /etc/conf.d/keymaps:KEYMAP,extended_keymaps-EXT_KEYMAPS
 101 <list> = /etc/conf.d/keymaps:KEYMAP,extended_keymaps-EXT_KEYMAPS
 102 <element> = /etc/conf.d/keymaps:KEYMAP,extended_keymaps-EXT_KEYMAPS
 103 <conf-file-name> = /etc/conf.d/keymaps
 104 <map-list> = KEYMAP,extended_keymaps-EXT_KEYMAPS
 105 <mapping> = KEYMAP
 106 <src-var> = KEYMAP
 107 <mapping> = extended_keymaps-EXT_KEYMAPS
 108 <src-var> = extended_keymaps
 109 <dst-var> = EXT_KEYMAPS
 110
 111
 112 2.3. Additional settings
 113
 114 If you encounter following error message: "Directories consolefonts,
 115 consoletrans, keymaps, unimaps not found.", you can provide path where
 116 those directories lie in your system by setting kbddir in configuration
 117 file (the same where you put mappings).
 118
 119
 120 3. Kernel parameters
 121
 122 If you create generic initramfs you can set up i18n by kernel
 123 parameters using variables listed in 2.1. (except of UNIKEYMAP
 124 and GRP_TOGGLE) The recommended minimum is: FONT and KEYMAP.