ACC SHELL

               Metadata in sysconfig files 
             ==============================


Author:  Ladislav Slezak <lslezak@suse.cz>
Last change: 2004-11-16


Introduction
------------

  Yast2 sysconfig editor can edit /etc/sysconfig files. In this editor users can
change values in easy way using GUI. Yast2 sysconfig editor needs more data
(metadata) to display and edit sysconfig variables - metadata was originaly
stored in meta_sys.config file in yast2-sysconfig package. This file contained
information about position in tree widget, allowed values, etc.

  This separation between data and metadata caused inconsistency - new variable
in sysconfig file had no metadata and removed variables still had metadata in
yast2 package. (If variable was renamed both problems occured...)

  There was also problem with maintenance of data and metadata: data were
maintained by package maintainer but metadata by yast2-sysconfig maintainer.

  The metadata should contain descriptions of actions required to start when a
variable is changed. So GUI user does't need to open terminal and write
commands manualy. This task can be very hard (or impossible) for beginner user.



Metadata - description of variable
----------------------------------

  At first here is a small example to see how metadata looks. Here is
part of /etc/sysconfig/boot file with new metadata:

## Path:	System/Boot
## Description:	Boot configuration
## Type:	yesno
## Default:	no
# 
# For interactive debugging of the startup process. If set
# to "yes" the system will ask whether to confirm every
# step of the boot process.
#
PROMPT_FOR_CONFIRM="no"


  Metadata are part of variable description comment, metadata line begins with
double hash character ("##"). It contains pairs <keyword>:<value>. More values
can be specified in comma separated list, values which contain comma or
space character have to be quoted (e.g. "value with spaces").

  Long values can be splitted to more lines. To use multiple values use
backslash (\) as the last character on the line. (Trailing backslash and double
hash character at beginning of the next line will be removed and lines will be
concatenated.)

  Normal comment (after single hash characer) is displayed as help text,
comment after three hash characer is ignored - part of comment can be hidden
for yast2 user.

  Metadata block have to be located at the beginnig of comment block. Metadata can
have any order in metadata block. (Exception is Description tag which is
related to the previous Path tag.)


Metadata keywords:
------------------

  There are two sets of metada keywords: descriptions and actions. Descriptions
describe variable - e.g. type of the variable, default value... They limit
possible values entered by user. Typos, invalid values or values out of range
can be avoided by defining right descriptions.

  Action keywords describe actions which are required to activate changes.
Usually it means starting SuSEconfig module and service restart or
reload.

  I. Descriptive keywords:

    Path - where variable will be located in the tree widget in yast, it's
	   valid for all following variables in the file - path have to be
	   specified at least in the first variable in the file. The first
	   character of subtree name should be upper case letter.

	   Use slash character ('/') as a path separator, if slash should be a
	   part of the path name put backslash before slash ('\/').
	   
	   Fillup utility adds missing variables at the end of output - if more
	   templates are merged to one sysconfig file and each template have
	   different path it is possible that variable with description comment
	   will be stored in another location in target file (this can happen
	   if variable is defined in more templates). In this case each path
	   specification should be located at unique variable or each variable
	   should have explicitly defined path.

    Description - description of the path, displayed if user selects the path in
	   tree instead of variable. It should contain description of whole
	   subtree - each path specification should have description. If path
	   has more than one description last found will be used.
	   
	   If more packages requires same base package then description should
	   be located only in the base package. If packages are independent
	   description should be located in the extra file (located in
	   yast2-sysconfig package).

	   The description is related to the previous Path keyword (which can be
	   located even in another (previous) variable).
	   
    Type - type of the variable. This keyword specifies the data type of value, it is
           used for checking entered value.

           Supported types:

	    Type			Valid values
	    ---------------------------------------------------------------------
	    string		any value
	    string(v1,v2,...)	value from list or any value
	    list(v1,v2,...)	only value from list
	    integer		integer
	    integer(min:max)	integer in specified range (one limit can be missing,
				use e.g. integer(0:) for values >= 0)
	    boolean		only "true" or "false"
	    yesno		only "yes" or "no"
	    ip			IPv4 or IPv6 adress (e.g. 10.20.0.1)
	    ip4			IPv4 adress
	    ip6			IPv6 adress
	    regexp(re)		only strings that matches regular expression re
				(POSIX Extended Regular Expression), e.g. use
				regexp(^0[0-7]*$) for octal values.
		
	    If this keyword is missing default value "string" will be used.

    Default - the default value of the variable. Valid value (allowed by keyword Type)
           which will be set if user click [Default] button in yast module.


  II. Activation keywords:

    PreSaveCommand - start bash command before variables are changed. Sometimes
	   it is required to do an action with old value (e.g. stop daemon
	   which name is changed)

    Config - start selected SuSEconfig/ULconfig modules

    ServiceReload - reload services if they are running (specify only the init
           script file names without the path)

    ServiceRestart - restart services if they are running

    Command - start command in the bash shell. It can be used for any action
	   which cannot be specified using above tags. Value specified by
	   Command keyword argument is a string. The specified command will be
	   executed by bash shell (using bash -c option) - it is be possible to
	   use all bash features (e.g. conditional execution (&&, ||), output
	   redirection...).

	   The string will not be parsed or changed by YaST2 (except removing
	   white spaces at the beginning and at the end of the string, multi
	   line strings will be merged to the one line).


    Use comma as a separator for Config, ServiceRestart and ServiceReload tags
    if more than one parameter is need.

    If the activation command would be too complex (too many dependences or
    checks) a note should be a part of the comment instead of activation metada
    - e.g. recommended yast2 module, where is the activation process documented

    The commands shouldn't do any dangerous actions - they will be probably
    started automatically by beginner user. There is an option to confirm each
    action in the yaST2 module for experts. Restart of some services should be
    used carefully, e.g. variable DISPLAYMANAGER requires xdm restart which
    kills current X session - required action should be only described in the
    comment in this case.

    Some variables are used in more sysconfig templates - this can cause
    problems if the actions in the templates are different.



  All keywords are optional.


Predefined paths
----------------

  All sysconfig variables are divided into basic categories:

Hardware - all hardware related settings (e.g. sysconfig files: sound, keyboard...)
System - basic system configuration (boot, suseconfig, cron, console, security...)
Desktop - desktop settings (kde, gnome, xdm...)
Applications - java, ispell, man...
Network - network services (apache, mail, nfs...)
Other - other settings which does not fit into classes above (This section will
    be also used as a fallback if no section is specified in sysconfig file - in this
    case name of subtree will be the file name.)

  In path specification should be used one path from list above as the first part
(e.g. path: Hardware/Joystick, path: System/Console). Depth of path can be
greater than two - e.g. System/Filesystem/Fam.

  Description of predefined paths and paths defined in more templates is read
from separate file, which is part of yast2-sysconfig package.
  

Missing metadata
----------------

  If variable does not have any metadata the previous one will be used. If previous
metadata is missing yast2 cannot offer predefined values to user. In this
case will be used "Type: string" as default metadata so user can enter any value. 

  
  Example (/etc/sysconfig/joystick):

## Path:        Hardware/Joystick
## Description: Joystick cofigurations
## Type:        string
## Default:     ""
## ServiceRestart: joystick
#
# Gameport module names
# (typically "ns558" for legacy gameport support)
#
GAMEPORT_MODULE_0=""
GAMEPORT_MODULE_1=""
GAMEPORT_MODULE_2=""
GAMEPORT_MODULE_3=""


  The comment description (and the metadata) will be used for all four variables.


Saving changed values in Yast2 sysconfig module
-----------------------------------------------

    When saving the changed variables yast2 sysconfig module
will do the following actions:

    - start PreSaveCommmand for each changed variable. If it returs non zero
      exit status then it is supposed that it failed and other activation
      commmands will be ignored for this variable.

    - save all changed variables

    - start all specified SuSEconfig modules

    - restart/reload specified services which are running (command
      "/etc/init.d/testservice status" returns 0).

    - start generic commands


  If activation commands are missing in the whole sysconfig file complete
SuSEconfig will be started for backward compatibility with old sysconfig files.
Some variables need no activation (e.g. options in /etc/sysconfig/boot file are
used only at boot), use empty Config: tag (or any from above tags) to not start
the SuSEconfig script - if some action tag is specified (even empty) the
backward compatible action (calling the SuSEconfig script) will not be started.

  Each command will be started only once to speed up the activation if more
modified variables need the same activation command. The commands are compared
without any parsing or semantic check when testing whether the command has
already been executed. For this reason the commands should be consistent at
least in one file (user usually changes only few variables which are in one
file).


Global activation keywords
--------------------------

  It will be possible to specify the action commands globally or for a group
of variables: if no action keyword is specified then action in the previous
variable is used - recursively search for action until it is found or the
beginning of the file is reached. So it is possible to write the activation
keywords only to the first variable's comment and they will be used for all
followning variables if they have no action tag specified.
    
  This feature should be used carefully especially in the sysconfig files which
are merged from many small parts, because fillup appends the new variables to
the end of file but existing variables are left in the original place.


Update problem
--------------

  At update old and new config files are merged by fillup utility, but old
comments are preserved (user's comments will not be deleted or changed...),
but metadata should be updated to new values.

  Every sysconfig file should have a template - even files created by Yast,
this is required for updating metadata during update of the package.