type

The type property controls variable type and thus (roughly) what are the possible values.

The property must be a single text value and be one of the following:

  • files:
    • text (default for all definitions)
    • bool
    • select
    • file
    • binfile
    • int
    • novalue
    • diag
  • directories:
    • dir
    • action
    • list

Files

text

A text value is simply one line of text, ie. an arbitrary string consisting of all characters except '\n'.

It has an additional property maxlen, limiting the number of characters the value can consist of (not including the terminating \0 character), with default value of 100. A maxlen of 0 means no limit.

It is the default type for files.

bool

A boolean value, ie. "1" (true) or "0" (false).

select

Lets the user select one of the values specified in the select property.

Examples of value definitions:

  1. without titles:
    select = { "no", "try", "always" }
    
  2. with titles:
    select = {
            { value: "no",     en: "don't use DHCP",        pl: "nie używaj DHCP" },
            { value: "try",    en: "use DHCP if available", pl: "użyj DHCP jeśli dostępne" },
            { value: "always", en: "depend on DHCP",        pl: "polegaj na DHCP" }
    }
    

file

Holds a text file editable by the user.

binfile

As above, but the value is binary (ie. not an ASCII text), thus not editable by the user. The interface should allow to upload the file or to fetch it from system path/URL.

int

An integer value, with lower and higher limits, both of which are optional. Example:

int = { min: "-100", max: "100" }

novalue

A placeholder variable without any value. May be useful as the type of a list element, ie. when the editable element name is sufficient (e.g. it's an IPv4 address).

diag

Variable holding a read-only, diagnosis value. The diagmime property holds variable's MIME content type.

Allowed MIME content types:

  • text/plain
  • text/html
  • image/png

Notes:

  • textual user interfaces may need to ignore/convert diagnosis messages of last two types,
  • variables of the diag type will usually have the value property set, so the diagnosis information doesn't get written to the disk (what in most cases would be useless).

Directories

dir

Simply a directory, used for organizing configuration in tree-like structure.

Can have a strict definition of variable order:

# fs:/dir.fc
type = "dir"
order = {
        "hostname", # display variable defined in fs:/dir/hostname.fc as first
        "country",
        "timezone",
        "ntp"
}

If you would like to make some configuration elements common and re-usable, make a subdirectory in /usr/share/fc/skel and use the skel property:

# fs:/dir.fc
type = "dir"
skel = { "bootable" }

# fs:skel:bootable/boot.fc
type = bool
title = { en: "Start the service with system boot" }

Contents of /usr/share/fc/skel/bootable/ will be treated exactly as if they were in /usr/share/fc/main/dir/.

action

Like dir, but with submit capability. Whenever the user submits an action directory, the script(s) defined in the onsubmit property should be executed, as described in 2.0/props/scripts.

list

List holds Flatconf variables which may be modified by the user. Lists are described in 2.0/lists.

value

Value to use instead of fetching it from file. In such case the value is also read-only and cannot be modified, thus there is no need to create any file representing the variable (however fc:/path/to/variable is still valid) - also during the upgrade process.

default

Contains the default, (raw) variable value, mostly used during upgrade process, but may also be used as a hint for the user.

Example:

default = "192.168.1.1/24"

examples

Defines examples of variable values.

  • simple
    examples = { "host1.isp.com", "router.lan" }
    
  • values depending on user language (e.g. for descriptions)
    examples = {
            en: { "NY, Some Street 11, rooftop",
                  "CA, 8th Street, IT dept" }
            pl: { "W-wa, ul. Kowalskiego 8, dach",
                  "K-ce, ul. Jacka i Placka 2, 3 piętro" }
    }
    
  • descriptions depending on user language
    examples = {
            { value: "-p tcp", en: "Match TCP/IP", pl: "Dopasuj TCP/IP" },
            { value: "-m state --state ESTABLISHED,RELATED",
              en: "Match existing connections",
              pl: "Dopasuj istniejące połączenia" }
    }
    
  • values and descriptions depending on user language
    examples = {
            en: {
    	  { value: "NY, Some Street 11, rooftop", en: "A location in New York" },
              { value: "SF, 8th Street, IT dept", en: "A location in San Francisco" }
            },
            pl: {
              { value: "W-wa, ul. Kowalskiego 8, dach", pl: "Położenie w Warszawie" },
              { value: "K-ce, ul. Jacka i Placka 2, 3 piętro", pl: "Położenie w Katowicach" }
            }
    }
    

regexp

Defines regular expressions that the value must satisfy.

Example:

# accept non-empty 1.2.3.4/mask
regexp = { "notempty", "cidr4" }

The values in the regexp property are names of FCML files in /usr/share/fc/regexp/ directory.

Example of /usr/share/fc/regexp/cidr4.fc file:

positive = {
	"/[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\/[0-9]{1,2}/" # weak match
}

#negative = { "/999.999.999.999\/99/" }

error = {
        en: "Value is not an IPv4 address in CIDR form",
        pl: "Wartość nie jest adresem IPv4 w formie CIDR"
}

examples = { "1.2.3.4/27", "192.168.1.1/24" }
  • positive - regular expression that the value must match,
  • negative - regular expression that the value must not match,
  • error - multilingual error to show the user when the value does not satisfy the regexp,
  • examples - examples of proper values (see the ''examples'' variable property), to be shown along with error message.

All regexp properties are optional. Empty values are not checked against regexps.

Supported regexp pattern modifiers (see PHP documentation):

  • i,
  • m,
  • s,
  • x,
  • A,
  • D,
  • U and
  • X.

notempty

If this property is present and has a value of 1, the variable cannot be set to an empty value.