unlang

title: unlang(5)

summary: FreeRADIUS Processing un\-language

text:
# unlang(5)

## NAME
unlang - FreeRADIUS Processing un-language

## DESCRIPTION
FreeRADIUS supports a simple processing language in its configuration files. We call it an "un-language" because the intention is NOT to create yet another programming language. If you need something more complicated than what is described here, we suggest using the Perl or Python modules rlm_perl, or rlm_python.

The goal of the language is to allow simple policies to be written with minimal effort. Those policies are then applied when a request is being processed. Requests are processed through virtual servers (including the default one), in the sections titled "authorize", "authenticate", "post-auth", "preacct", "accounting", "pre-proxy", "post-proxy", and "session".

These policies cannot be used in any other part of the configuration files, such as module or client configuration.

## KEYWORDS
The keywords for the language are a combination of pre-defined keywords, and references to loadable module names. We document only the pre-defined keywords here.

Subject to a few limitations described below, any keyword can appear in any context. The language consists of a series of entries, each one line. Each entry begins with a keyword. Entries are organized into lists. Processing of the language is line by line, from the start of the list to the end. Actions are executed per-keyword.

module-name[.section-name]

A reference to the named module. When processing reaches this point, the pre-compiled module is called. The module may succeed or fail, and will return a status to "unlang" if so. This status can be tested in a condition. See the "Simple Conditions" text in the CONDITIONS section, and MODULE RETURN CODES, below. If a section-name is provided, it will cause the module to execute as if it were listed in the named section.

```
	chap  # call the CHAP module

	sql   # call the SQL module

	...
```

if

Checks for a particular condition. If true, the block after the condition is processed. Otherwise, the block is ignored. See CONDITIONS, below, for documentation on the format of the conditions.

```
	if (condition) {

		...

	}
```

else

Define a block to be executed only if the previous "if" condition returned false.

```
	else {

		...

	}
```

elsif

Define a block to be executed only if the previous "if" condition returned false, and if the specified condition evaluates to true.

```
	elsif (condition) {

		...

	}
```

foreach

Loops over values of an attribute, running the block for each value. The return value of the block is the return value of the last statement executed. The loop can be exited early by using the "break" keyword. Unlike other languages, "break" here means "exit the loop at the next iteration", not "exit the loop now". The result is that any statements after the "break" keyword will still be executed. We recommend using "break" only when it is the last statement in a "foreach" block. Inside of the "foreach" block, the attribute which is being looped over can be referenced as "Foreach-Variable-#". Where "#" is the depth of the loop, starting at "0". e.g. "Foreach-Variable-0". The loops can be nested up to eight (8) deep, though this is not recommended.

```
	foreach &Attribute-Reference {

		...

	}
```

switch

A "switch" statement takes one argument, and contains a series of "case" statements. When a "switch" statement is encountered, the argument from the "switch" is evaluated in turn against the argument from each "case" statement. The first "case" statement which matches is executed. All other "case" statements are ignored. A default "case" statement can be defined, by omitting its argument. If the argument is a double quoted string (e.g. "%{exec:1 + 2}", it is expanded as described in the DATA TYPES section, below. The match is then performed on the string returned from the expansion. If the argument is an attribute reference (e.g. &User-Name), then the match is performed on the value of that attribute. Otherwise, the argument is taken to be a literal string, and matching is done via simple comparison.

No statement other than "case" can appear in a "switch" block.

```
	switch <argument> {

		...

	}
```

case

Provides a place-holder which matches the argument of a parent "switch" statement. A "case" statement cannot appear outside of a "switch" block.

If the argument is a double quoted string (e.g. "%{exec:1 + 2}", it is expanded as described in the DATA TYPES section, below. The match is then performed on the string returned from the expansion. If the argument is an attribute reference (e.g. &User-Name), then the match is performed on the value of that attribute. Otherwise, the argument is taken to be a literal string, and matching is done via simple comparison.

```
	case <argument> {

		...

	}
```

A default entry can be defined by omitting the argument, as given below. This entry will be used if no other "case" entry matches. Only one default entry can exist in a "switch" section.

```
	case {

		...

	}
```

update

Update a particular attribute list, based on the attributes given in the current block.

```
	update <list> {

		&Attribute-Reference = value

		...

	}
```

The <list> can be one of "request", "reply", "proxy-request", "proxy-reply", "coa", "disconnect", "session-state", or "control". As of Version 3, the <list> can be omitted, in which case "request" is assumed.

The "control" list is the list of attributes maintained internally by the server that controls how the server processes the request. Any attribute that does not go in a packet on the network will generally be placed in the "control" list.

For EAP methods with tunneled authentication sessions (i.e. PEAP and EAP-TTLS), the inner tunnel session can also reference "outer.request", "outer.reply", and "outer.control". Those references allow you to address the relevant list in the outer tunnel session.

The "coa" and "disconnect" sections can only be used when the server receives an Access-Request or Accounting-Request. Use "request" and "reply" instead of "coa" when the server receives a CoA-Request or Disconnect-Request packet.

Adding one or more attributes to either of the "coa" or "disconnect" list causes server to originate a CoA-Request or Disconnect-Request packet. That packet is sent when the current Access-Request or Accounting-Request has been finished, and a reply sent to the NAS. See raddb/sites-available/originate-coa for additional information.

The "session-state" list is primarily used for EAP. Attributes put into the "session-state" list are saved for the next packet in the session. They are automatically retrieved when the next packet is received.

The only contents permitted in an "update" section are attributes and values. The contents of the "update" section are described in the ATTRIBUTE REFERENCE and ATTRIBUTE ASSIGNMENT sections below.

redundant

This section contains a simple list of modules. The first module is called when the section is being processed. If the first module succeeds in its operation, then the server stops processing the section, and returns to the parent section. If, however, the module fails, then the next module in the list is tried, as described above. The processing continues until one module succeeds, or until the list has been exhausted.

Redundant sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list.

```
	redundant {

		sql1	# try this

		sql2	# try this only if sql1 fails.

		...

	}
```

load-balance

This section contains a simple list of modules. When the section is entered, one module is chosen at random to process the request. All of the modules in the list should be the same type (e.g. ldap or sql). All of the modules in the list should behave identically, otherwise the load-balance section will return different results for the same request. Load-balance sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list.

```
	load-balance {

		ldap1	# 50% of requests go here

		ldap2	# 50% of requests go here

	}
```

In general, we recommend using "redundant-load-balance" instead of "load-balance".

redundant-load-balance

This section contains a simple list of modules. When the section is entered, one module is chosen at random to process the request. If that module succeeds, then the server stops processing the section. If, however, the module fails, then one of the remaining modules is chosen at random to process the request. This process repeats until one module succeeds, or until the list has been exhausted. All of the modules in the list should be the same type (e.g. ldap or sql). All of the modules in the list should behave identically, otherwise the load-balance section will return different results for the same request.

Load-balance sections can contain only a list of modules, and cannot contain keywords that perform conditional operations (if, else, etc) or update an attribute list. Please see raddb/radiusd.conf "instantiate" section for more configuration examples.

```
	redundant-load-balance {

		ldap1	# 50%, unless ldap2 is down, then 100%

		ldap2	# 50%, unless ldap1 is down, then 100%

	}
```

return

Returns from the current top-level section, e.g. "authorize" or "authenticate". This keyword is mainly used to avoid layers of nested "if" and "else" statements.

```
	authorize {

		if (...) {

			...

			return

		}

		...  # this is never reached when the "if"

		...  # statement is executed

	}
```

## ATTRIBUTE REFERENCES
Attributes may be referenced via the following syntax:

```
	&Attribute-Name
	&Attribute-Name:TAG
	&Attribute-Name[NUM]
	&<list>:Attribute-Name
	&<list>:Attribute-Name:TAG[NUM]
```

Where <list> is one of "request", "reply", "control", "proxy-request", "proxy-reply", or "outer.request", "outer.reply", "outer.control", "outer.proxy-request", or "outer.proxy-reply". just as with the "update" section, above. The "<list>:" prefix is optional, and if omitted, is assumed to refer to the "request" list.

The TAG portion is a decimal integer between 1 and 31. Please see RFC 2868 for more information about tags. Tags can only be used for attributes which are marked in the dictionary as "has_tag".

The NUM portion is used when there are multiple attributes of the same name in a list. The "Attribute-Name" reference will return the first attribute. Using an array offset allows the policy to refer to the second and subsequent attributes.

If '*' is used in the NUM portion, it evaluates to all instances of the attribute in the request.

If 'n' is used in the NUM portion, it evaluates to the last instance of the attribute in the request.

When an attribute name is encountered, the given list is examined for an attribute of the given name. Some examples are:

```
	User-Name

	request:User-Name # same as above

	reply:User-Name

	Tunnel-Password:1

	Cisco-AVPAir[2]

	outer.request:User-Name # from inside of a TTLS/PEAP tunnel
```

Note that unlike C, there is no way to define new attributes at run-time. They MUST be declared in a dictionary file, and loaded when the server starts.

All attributes are defined in the dictionaries that accompany the server. These definitions define only the name and type, and do not define the value of the attribute. When the server receives a packet, it uses the packet contents to look up entries in the dictionary, and instantiates attributes with a name taken from the dictionaries, and a value taken from the packet contents. This process means that if an attribute does not exist, it is usually because it was not contained in a packet that the server received.

Once the attribute is instantiated, it is added to a list. It can then be referenced, updated, replaced, etc.

## CONDITIONS
The conditions are similar to C conditions in syntax, though quoted strings are supported, as with the Unix shell.

Simple

conditions

```
	(foo)
```

Evaluates to true if 'foo' is a non-empty string (single quotes, double quotes, or back-quoted). Also evaluates to true if 'foo' is a non-zero number. Note that the language is poorly typed, so the string "0000" can be interpreted as a numerical zero. This issue can be avoided by comparing strings to an empty string, rather than by evaluating the string by itself.

If the word 'foo' is not a quoted string, then it can be taken as a reference to a named attribute. See "Referencing attribute lists", below, for examples of attribute references. The condition evaluates to true if the named attribute exists.

Otherwise, if the word 'foo' is not a quoted string, and is not an attribute reference, then it is interpreted as a reference to a module return code. The condition evaluates to true if the most recent module return code matches the name given here. Valid module return codes are given in MODULE RETURN CODES, below.

Negation

```
	(!foo)
```

Evaluates to true if 'foo' evaluates to false, and vice-versa.

Short-circuit operators

```
	(foo || bar)

	(foo && bar)
```

"&&" and "||" are short-circuit operators. "&&" evaluates the first condition, and evaluates the second condition if and only if the result of the first condition is true. "||" is similar, but executes the second command if and only if the result of the first condition is false.

Comparisons

```
	(foo == bar)
```

Compares 'foo' to 'bar', and evaluates to true if the comparison holds true. Valid comparison operators are "==", "!=", "<", "<=", ">", ">=", "=~", and "!~", all with their usual meanings. The operators ":=", "^=" and "=" are assignment operators, and are not allowed for comparisons.

The operators "<", "<=", ">", and ">=" are also allowed for checking that an IP address is contained within a network. For example:

```
	if (<ipaddr>192.0.2.1 < 192.0.2.0/24) {
```

This comparison succeeds, because the address 192.0.2.1 is contained within the network 192.0.2.0/24.

Attribute Comparisons

When doing attribute comparisons, the data type of the attribute is used to determine the data type of the right-hand side argument.

```
	(&User-Name == "foo")
```

Compares the value of the User-Name attribute to the string 'foo', and evaluates to true if the comparison holds true.

Similarly,

```
	(&Framed-IP-Address == 192.0.2.1)
```

Compares the value of the Framed-IP-Address attribute to the IP address 192.0.2.1. This IP address does not need to be quoted.

Inter-Attribute Comparisons

```
	(&User-Name == &Filter-Id)
```

Compares the value of the User-Name attribute to the contents of the Filter-Id attribute, and evaluates to true if the comparison holds true. Unlike the previous example, this comparison is done in a type-safe way. For example, comparing the IP addresses 1.2.3.4 and 127.0.0.1 as strings will return different results than comparing them as IP addresses.

The "&" character in the condition means that the comparison "refers" to the Filter-Id attribute. If left off, it means that the User-Name attribute is compared to the literal string "Filter-Id".

Where the left-hand side is an attribute, the "&" can be omitted. However, it is allowed for backwards compatibility. e.g. The comparison "(&User-Name == &Filter-Id)" is equivalent to the example above.

We recommend using attribute references instead of printing attributes to a string, e.g. (User-Name == "%{Filter-Id}"). Attribute references will be faster and more efficient.

The conditions will check only the first occurrence of an attribute. If there is more than one instance of an attribute, the following syntax should be used:

```
	(&Attribute-Name[*] == "foo")
```

Using the "[*]" syntax means that it checks all of the instances of the named attribute. If one attribute matches, the condition succeeds. If none match, the condition fails.

Casts

```
	(<type>foo == bar)
```

The left-hand-side of a condition can be "cast" to a specific data type. The data type must be one which is valid for the dictionaries. e.g. "integer", "ipaddr", etc.

The comparison is performed in a type-safe way, as with "Inter-Attribute Comparisons", above. Both sides of the condition are parsed into temporary attributes, and the attributes compared via type-specific methods. The temporary attributes have no other effect, and are not saved anywhere.

Casting allows conditions to perform type-specific comparisons. In previous versions of the server, the data would have to be manually placed into an intermediate attribute (or attributes), and then the attribute (or attributes) compared. The use of a cast allows for simpler policies.

Casts are allowed only on the left-hand side argument of a condition.

Conditions may be nested to any depth, subject only to line length limitations (8192 bytes).

## DATA TYPES
There are only a few data types supported in the language. Reference to attributes, numbers, and strings. Any data type can appear in stand-alone condition, in which case they are evaluated as described in "Simple conditions", above. They can also appear (with some exceptions noted below) on the left-hand or on the right-hand side of a comparison.

numbers

Numbers are composed of decimal digits. Floating point, hex, and octal numbers are not supported. The maximum value for a number is machine-dependent, but is usually 32-bits, including one bit for a sign value.

word

Text that is not enclosed in quotes is interpreted differently depending on where it occurs in a condition. On the left hand side of a condition, it is interpreted as a reference to an attribute. On the right hand side, it is interpreted as a simple string, in the same manner as a single-quoted string. Using attribute references permits limited type-specific comparisons, as seen in the examples below.

```
	if (&User-Name == "bob") {

		...

	if (&Framed-IP-Address > 127.0.0.1) {

		...

	if (&Service-Type == Login-User) {
```

"strings"

Double-quoted strings are expanded by inserting the value of any attributes (see ATTRIBUTE REFERENCES, below) before being evaluated. If the result is a number it is evaluated in a numerical context. String length is limited by line-length, usually about 8000 characters. A double quote character can be used in a string via the normal back-slash escaping method. ("like \"this\" !")

'strings'

Single-quoted strings are evaluated as-is. Their values are not expanded as with double-quoted strings above, and they are not interpreted as attribute references.

`strings`

Back-quoted strings are evaluated by expanding the contents of the string, as described above for double-quoted strings. The resulting command given inside of the string in a sub-shell, and taking the output as a string. This behavior is much the same as that of Unix shells. Note that for security reasons, the input string is split into command and arguments before string expansion is done.

For performance reasons, we suggest that the use of back-quoted strings be kept to a minimum. Executing external programs is relatively expensive, and executing a large number of programs for every request can quickly use all of the CPU time in a server. If you believe that you need to execute many programs, we suggest finding alternative ways to achieve the same result. In some cases, using a real language may be sufficient.

/regex/im

These strings are valid only on the right-hand side of a comparison, and then only when the comparison operator is "=~" or "!~". They are regular expressions, as implemented by the local regular expression library on the system. This is usually Posix regular expressions. The trailing 'i' is optional, and indicates that the regular expression match should be done in a case-insensitive fashion.

The trailing 'm' is also optional, and indicates that carrot '^' and dollar '$' anchors should match on new lines as well as at the start and end of the subject string.

If the comparison operator is "=~", then parentheses in the regular expression will define variables containing the matching text, as described below in the ATTRIBUTE REFERENCES section.

## EXPANSIONS
Attributes are expanded using the ATTRIBUTE REFERENCE syntax described above, and surrounding the reference with "%{...}"

```
	%{Attribute-Reference}
```

The result will be a string which contains the value of the attribute which was referenced, as a printable string. If the attribute does not exist, the result will be an empty string.

Results of regular expression matches

If a regular expression match has previously been performed, then the special variable %{0} will contain a copy of the matched portion of the input string. The variables %{1} through %{32} will contain the substring matches, starting from the left-most capture group, onwards. If there are more than 32 capture groups, the additional results will not be accessible. If the server is built with libpcre, the results of named capture groups are available using the "%{regex:capture group}" expansion. They will also be accessible using the variables described above. Every time a regular expression is evaluated, whether it matches or not, the capture group values will be cleared.

Obtaining results from databases

It is useful to query a database for some information, and to use the result in a condition. The following syntax will call a module, pass it the given string, and replace the string expansion with the resulting string returned from the module.

```
	%{module: string ...}
```

The syntax of the string is module-specific. Please read the module documentation for additional details.

Conditional Syntax

Conditional syntax similar to that used in Unix shells may also be used. %{%{Foo}:-bar}

If %{Foo} has a value, returns that value.

Otherwise, returns literal string "bar".

%{%{Foo}:-%{Bar}}

If %{Foo} has a value, returns that value.

Otherwise, returns the expansion of %{Bar}. These conditional expansions can be nested to almost any depth, such as with %{%{One}:-%{%{Two}:-%{Three}}}

String lengths and arrays

Similar to a Unix shell, there are ways to reference string lengths, and the second or more instance of an attribute in a list. If you need more than this functionality, we suggest using a real language. %{strlen:string}

The number of characters in "string". If "string" does not exist, then the length also does not exist, instead of being zero. The "string" is expanded before the length is taken.

%{integer:Attribute-Name}

The integer value of the Attribute-Name, instead of the enumerated name. e.g. If a request contains "Service-Type = Login-User", the expansion of %{integer:Service-Type} will yield "1".

%{hex:Attribute-Name}

The hex value of the Attribute-Name, as a series of hex digits. e.g. If a request contains "Framed-IP-Address = 127.0.0.1", the expansion of %{hex:Framed-IP-Address} will yield "0x7f000001".

%{Attribute-Name[#]}

The number of instances of Attribute-Name. e.g. If a request contains "User-Name = bob", the expansion of %{User-Name[#]} will yield "1".

%{Attribute-Name[*]}

All values of Attribute-Name, concatenated together with ',' as the separator.

%{List-Name:[#]}

The number of attributes in the named list.

%{List-Name:[*]}

All values of attributes in the named-list, concatenated together with ',' as the separator. Use the %{pairs:} xlat to get a list of attributes and values. e.g. If a response contains "Reply-Message = 'Hello', Reply-Message = 'bob' the expansion of "%{reply:Reply-Message[*]} will yield "Hello\nbob"

## ATTRIBUTE ASSIGNMENTS
The attribute lists described above may be edited by listing one or more attributes in an "update" section. Once the attributes have been defined, they may be referenced as described above in the ATTRIBUTE REFERENCES section.

The following syntax defines attributes in an "update" section. Each attribute and value has to be all on one line in the configuration file. There is no need for commas or semi-colons after the value.

```
	Attribute-Reference = value
```

Attribute Reference

The Attribute-Reference must be a reference (see above), using a name previously defined in a dictionary. If an undefined name is used, the server will return an error, and will not start.

Operators

The operator used to assign the value of the attribute may be one of the following, with the given meaning.

=

Add the attribute to the list, if and only if an attribute of the same name is not already present in that list.

:=

Add the attribute to the list. If any attribute of the same name is already present in that list, its value is replaced with the value of the current attribute.

+=

Add the attribute to the tail of the list, even if attributes of the same name are already present in the list. When the right hand side of the expression resolves to multiple values, it means add all values to the tail of the list.

^=

Add the attribute to the head of the list, even if attributes of the same name are already present in the list. When the right hand side of the expression resolves to multiple values, it means prepend all values to the head of the list.

Enforcement and Filtering Operators

The following operators may also be used in addition to the ones listed above. Their function is to perform enforcement or filtering on attributes in a list. -=

Remove all matching attributes from the list. Both the attribute name and value have to match in order for the attribute to be removed from the list.

==

Keep all matching attributes. Both the attribute name and value have to match in order for the attribute to remain in the list. Note that this operator is very different than the '=' operator listed above!

!=

Keep all attributes with matching name, and value not equal to the given one.

<

Keep all attributes having values less than the value given here. Any larger value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=".

<=

Keep all attributes having values less than, or equal to, the value given here. Any larger value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=".

>

Keep all attributes having values greater than the value given here. Any smaller value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=".

>=

Keep all attributes having values greater than, or equal to, the value given here. Any smaller value is replaced by the value given here. If no attribute exists, it is added with the value given here, as with "+=".

!*

Delete all occurrences of the named attribute, no matter what the value.

=~

Keep all attributes having values which match the given regular expression. If no attribute matches, nothing else is done.

!~

Keep all attributes having values which fail to match the given regular expression. If no attribute matches, nothing else is done.

Values

The value can be an attribute reference, or an attribute-specific string. When the value is an attribute reference, it must take the form of "&Attribute-Name". The leading "&" signifies that the value is a reference. The "Attribute-Name" is an attribute name, such as "User-Name" or "request:User-Name". When an attribute reference is used, both attributes must have the same data type. For example, "User-Name := &NAS-Port" is invalid, because "User-Name" is a string, and "NAS-Port" is an integer.

We recommend using the form "Attribute-1 = &Attribute-2" for updates, instead of "Attribute-1 = "%{Attribute-2}". The first version will copy the attribute data, no matter what its form. The second version will print the Attribute-2 to a string, and then parse it to create the value for Attribute-1. This second version is slower and more fragile than the first one.

When the value is an attribute-specific string, it can be a string, integer, IP address, etc. The value may be expanded as described above in the DATA TYPES section, above. For example, specifying "Framed-IP-Address = 127.0.0.1" will cause the "Framed-IP-Address" attribute to be set to the IP address "127.0.0.1". However, using "Framed-IP-Address := module to be run with a string "127.0.0.1". The output of the "echo" module will then be parsed as an IP address, and placed into the Framed-IP-Address attribute.

This flexibility means that you can assign an IP address by specifying it directly, or by having the address returned from a database query, or by having the address returned as the output of a program that is executed.

When string values are finally assigned to an attribute, they can have a maximum length of 253 characters. This limit is due in part to both protocol and internal server requirements. That is, the strings in the language can be nearly 8k in length, say for a long SQL query. However, the output of that SQL query should be no more than 253 characters in length.

## OTHER KEYWORDS
Other keywords in the language are taken from the names of modules loaded by the server. These keywords are dependent on both the modules, and the local configuration.

Some use keywords that are defined in the default configuration file are:

fail

Cause the request to be treated as if a database failure had occurred.

noop

Do nothing. This also serves as an instruction to the configurable failover tracking that nothing was done in the current section.

ok

Instructs the server that the request was processed properly. This keyword can be used to over-ride earlier failures, if the local administrator determines that the failures are not catastrophic.

reject

Causes the request to be immediately rejected

## MODULE RETURN CODES
When a module is called, it returns one of the following codes to "unlang", with the following meaning.

```
	notfound        information was not found

	noop            the module did nothing

	ok              the module succeeded

	updated         the module updated the request

	fail            the module failed

	reject          the module rejected the request

	userlock        the user was locked out

	invalid         the configuration was invalid

	handled         the module has handled the request itself
```

These return codes can be tested for in a condition, as described above in the CONDITIONS section.

See also the file doc/configurable_failover for additional methods of trapping and modifying module return codes.

## FILES
/etc/raddb/radiusd.conf

## SEE ALSO
radiusd.conf(5), dictionary(5)

## AUTHOR
Alan DeKok <aland@deployingradius.com>


users

package: freeradius

title: users(5)

text:
# users(5)

## NAME
users - user authorization file for the FreeRADIUS server

## DESCRIPTION
The users files reside in the files module configuration directory, by default /etc/raddb/mods-config/files/. It contains a series of configuration directives which are used by the files module to decide how to authorize and authenticate each user request.

Every line starting with a hash sign ('#') is treated as comment and ignored.

Each entry of the file begins with a username, followed by a (possibly empty) list of check items, all on one line. The next line begins with a tab, and a (possibly empty) list of reply items. Each item in the check or reply item list is an attribute of the form name = value. Multiple items may be placed on one line, in which case they must be separated by commas. The reply items may be specified over multiple lines, in which case each line must end with a comma, and the last line of the reply items must not end with a comma.

The check items are a list of attributes used to match the incoming request. If the username matches, AND all of the check items match the incoming request, then the reply items are added to the list of attributes which will be used in the reply to that request. This process is repeated for all of the entries in the users file.

If the incoming request matches NO entry, then the request is rejected.

## CAVEATS
The special keyword DEFAULT matches any usernames.

The entries are processed in order, from the top of the users file, on down. If an entry contains the special item Fall-Through = No as a reply attribute, then the processing of the file stops, and no more entries are matched. Any reply item list without any Fall-Through attribute is treated as though it included a Fall-Through = No attribute.

If an entry contains the special item Fall-Through = Yes as a reply attribute, then the processing proceeds to the next entry in order.

Care should be taken when using Fall-Through. The server should be tested in debugging mode with a number of test requests, in order to verify that the configured entries behave as expected.

The special attribute Auth-Type is used to identify the authentication type to be used for that user. See the dictionary file for a list of permitted values for the Auth-Type attribute.

Once the users file has been processed, the request is authenticated, using the method given by Auth-Type.

## OPERATORS
Additional operators other than = may be used for the attributes in either the check item, or reply item list. The following is a list of operators, and their meaning.

Attribute = Value

Not allowed as a check item for RADIUS protocol attributes. It is allowed for server configuration attributes (Auth-Type, etc), and sets the value of on attribute, only if there is no other item of the same attribute.

As a reply item, it means "add the item to the reply list, but only if there is no other item of the same attribute."

Attribute := Value

Always matches as a check item, and replaces in the configuration items any attribute of the same name. If no attribute of that name appears in the request, then this attribute is added.

As a reply item, it has an identical meaning, but for the reply items, instead of the request items.

Attribute == Value

As a check item, it matches if the named attribute is present in the request, AND has the given value.

Not allowed as a reply item.

Attribute += Value

Always matches as a check item, and adds the current attribute with value to the tail of the list of configuration items.

As a reply item, it has an identical meaning, but the attribute is added to the tail of the reply items list.

Attribute ^= Value

Always matches as a check item, and adds the current attribute with value to the head of the list of configuration items.

As a reply item, it has an identical meaning, but the attribute is added to the head of the reply items list.

Attribute != Value

As a check item, matches if the given attribute is in the request, AND does not have the given value.

Not allowed as a reply item.

Attribute > Value

As a check item, it matches if the request contains an attribute with a value greater than the one given.

Not allowed as a reply item.

Attribute >= Value

As a check item, it matches if the request contains an attribute with a value greater than, or equal to the one given.

Not allowed as a reply item.

Attribute < Value

As a check item, it matches if the request contains an attribute with a value less than the one given.

Not allowed as a reply item.

Attribute <= Value

As a check item, it matches if the request contains an attribute with a value less than, or equal to the one given.

Not allowed as a reply item.

Attribute =* Value

As a check item, it matches if the request contains the named attribute, no matter what the value is.

Not allowed as a reply item.

Attribute !* Value

As a check item, it matches if the request does not contain the named attribute, no matter what the value is.

Not allowed as a reply item.

## EXAMPLES

```
bob	Cleartext-Password := "hello"
```

Requests containing the User-Name attribute, with value "bob", will be authenticated using the "known good" password "hello". There are no reply items, so the reply will be empty.

```
DEFAULT Service-Type == Framed-User, Framed-Protocol == PPP

	Service-Type = Framed-User,

	Framed-Protocol = PPP,

	Fall-Through = Yes
```

If the request packet contains the attributes Service-Type and Framed-Protocol, with the given values, then include those attributes in the reply. That is, give the user what they ask for. This entry also shows how to specify multiple reply items.

See the users file supplied with the server for more examples and comments.

## HINTS
Run the server in debugging mode (-X), and use the radclient program to send it test packets which you think will match specific entries. The server will print out which entries were matched for that request, so you can verify your expectations. This should be the FIRST thing you do if you suspect problems with the file.

Care should be taken when writing entries for the users file. It is easy to misconfigure the server so that requests are accepted when you wish to reject them. The entries should be ordered, and the Fall-Through item should be used ONLY where it is required.

Entries rejecting certain requests should go at the top of the file, and should not have a Fall-Through item in their reply items. Entries for specific users, who do not have a Fall-Through item, should come next. Any DEFAULT entries should usually come last, except as fall-through entries that set reply attributes.

## FILES
/etc/raddb/mods-config/files/

## SEE ALSO
radclient(1), radiusd(8), dictionary(5),

## AUTHOR
The FreeRADIUS team.


freetds.conf

package: freetds-utils

title: freetds.conf(5)

summary: configuration file for FreeTDS

text:
# freetds.conf(5)

## NAME
freetds.conf — configuration file for FreeTDS

## SYNOPSIS
The freetds.conf file describes Sybase and Microsoft database servers to the FreeTDS library. It comprises sections headed by a servername, followed by a list of connection properties denoted as name-value pairs. Defaults are defined via a [global] section. This file supersedes the interfaces file that Sybase defines for the same purpose, although the latter is still supported.

## DESCRIPTION
A section begins with a servername — the name of the server — in square brackets. The servername is chosen at the client's descretion. (One exception: with Sybase ASA the servername must match the database name to be used.)

Sections contain properties, one per line, in the form

name = value

where name is the connection property to be described. Servernames and properties are not case sensitive. Values are case-preserving i.e., copied literally. Comments begin with either a semicolon (‘;’) or pound sign (‘#’) and continue to end of line. Blank lines are ignored. Whitespace surrounding the ‘=’ is ignored.

## PROPERTIES
client charset

encoding of client data; overrides locale(1) settings Domain:

iconv character set names

Default:

ISO-8859-1

connect timeout

seconds to wait for response from connect request Domain:

0 to MAX_INT

Default:

none

debug flags

logging granularity Domain:

32-bit integer

Default:

0x4fff

dump file

specifies location of a logfile and turns on logging Domain:

valid file name

Default:

none

dump file append

log data appended to file instead of re-writing for each connection Domain:

yes/no

Default:

no

emulate little endian

forces big endian machines to act as little endian to communicate with Microsoft Servers Domain:

yes/no

Default:

no

encryption

off

disables encryption

request

use if available (default when tds version greater than 7.0)

required

allow encrypted connections only

host

Name of the host the server is running on. Domain:

host name or IP address

Default:

SYBASE

initial block size

maximum size of a protocol block Domain:

multiple of 512

Default:

512

instance

name of Microsoft SQL Server instance to connect to (supersedes port) Domain:

instance name

Default:

none

port

port number that the server is listening to Domain:

any valid port

Default:

TDS 5.0, 5000; TDS 7.0 and up, 1433

tds version

TDS protocol version to use Domain:

4.2, 5.0, 7.0, 7.1, 7.2

Default:

--with-tdsver value (5.0 if unspecified)

text size

default value of TEXTSIZE, in bytes Domain:

0 to 4,294,967,295

Default:

4,294,967,295

timeout

seconds to wait for response to a query Domain:

0 to MAX_INT

Default:

none (wait forever)

Do not define both port and instance. One implies the other.

Boolean property values may be denoted as on/off, true/false, or 1/0.

### DEBUG FLAGS
The log's granularity can be controlled with the debug flags property.

Value

Meaning

0x02

severe error

0x04

error

0x08

warning

0x10

network

0x20

information level 1

0x40

information level 2

0x80

function trace and info

0x1000

show pid

0x2000

show time

0x4000

show source level info (source file and line)

0x8000

thread id (not implemented).

## NAMES AND LOCATIONS
The file is normally named /etc/freetds.conf or ${HOME}/.freetds.conf. That name can be overridden with the FREETDSCONF environment variable.

FreeTDS will search conf files for a servername in the following order:

- a filename set programatically via dbsetifile() that is in .conf format

- a filename in the environment variable FREETDSCONF that is in .conf format

- ${HOME}/.freetds.conf if extant

- /etc/freetds/freetds.conf

The search stops with the first file containing the servername.

If no conf file is found, FreeTDS searches for an interfaces file in the following order:

- a filename set programatically via dbsetifile() that is in interfaces format

- ${HOME}/.interfaces

- $SYBASE/interfaces (where $SYBASE is an environment variable)

If the requested servername is not found in any configuration file, the fallback mechanism is:

- attempt to convert the name to an IP address with inet_addr(3), else

- attempt to convert the name to an IP address with gethostbyname(3), else

- attempt to look up the literal name “SYBASE”

## ENVIRONMENT
FREETDSCONF

overrides name and location of the system-wide conf file

TDSDUMP

overrides the name and location of the FreeTDS log file

TDSDUMPCONFIG

specifies a name and location of a file that logs the search of configuration files

TDSHOST

overrides the host property

TDSPORT

overrides the port property

TDSQUERY

synonym for DSQUERY, the default servername

TDSVER

overrides the version specified in the freetds.conf

The environment variables TDSVER, TDSDUMP, TDSPORT, TDSQUERY, and TDSHOST override values set by a .conf or interfaces file.

## FILES
/etc/freetds/freetds.conf, ${HOME}/.freetds.conf

## SEE ALSO
FreeTDS User Guide


netrc

package: ftp

title: netrc(5)

summary: user configuration for ftp

text:
# netrc(5)

## NAME
netrc, .netrc — user configuration for ftp

## DESCRIPTION
This file contains configuration and autologin information for the File Transfer Protocol client ftp(1).

The .netrc file contains login and initialization information used by the auto-login process. It resides in the user's home directory. The following tokens are recognized; they may be separated by spaces, tabs, or new-lines:

machine name

Identify a remote machine name. The auto-login process searches the .netrc file for a machine token that matches the remote machine specified on the ftp command line or as an open command argument. Once a match is made, the subsequent .netrc tokens are processed, stopping when the end of file is reached or another machine or a default token is encountered.

default

This is the same as machine name except that default matches any name. There can be only one default token, and it must be after all machine tokens. This is normally used as:

default login anonymous password user@site

thereby giving the user automatic anonymous ftp login to machines not specified in .netrc. This can be overridden by using the -n flag to disable auto-login.

login name

Identify a user on the remote machine. If this token is present, the auto-login process will initiate a login using the specified name.

password string

Supply a password. If this token is present, the auto-login process will supply the specified string if the remote server requires a password as part of the login process. Note that if this token is present in the .netrc file for any user other than anonymous, ftp will abort the auto-login process if the .netrc is readable by anyone besides the user.

account string

Supply an additional account password. If this token is present, the auto-login process will supply the specified string if the remote server requires an additional account password, or the auto-login process will initiate an ACCT command if it does not.

macdef name

Define a macro. This token functions like the ftp macdef command functions. A macro is defined with the specified name; its contents begin with the next .netrc line and continue until a null line (consecutive new-line characters) is encountered. If a macro named init is defined, it is automatically executed as the last step in the auto-login process.

## SEE ALSO
ftp(1), ftpd(8)


fusesmb.conf

package: fuse-smb

title: fusesmb.conf(5)

summary: the configuration file for fusesmb

text:
# fusesmb.conf(5)

## NAME
fusesmb.conf - the configuration file for fusesmb

## FILE FORMAT
The file consists of sections and parameters. A section begins with the name of the section in square brackets and continues until the next section begins. Sections contain parameters of the form: name = value.

The file is line-based - that is, each newline-terminated line represents either a comment, a section name or a parameter.

Section and parameter names are not case sensitive.

Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is discarded. Leading, trailing and internal whitespace in section and parameter names is irrelevant. Leading and trailing whitespace in a parameter value is discarded. Internal whitespace within a parameter value is retained verbatim.

Any line beginning with a semicolon (``;'') or a hash (``#'') character is ignored, as are lines containing only whitespace.

## SPECIAL SECTIONS
fusesmb.conf can contain the following sections:

The [global] section

Section for global parameters.

The [ignore] section

Section for specifying servers and/or workgroups that should not be listed.

The [/SERVER] section

Section for server-specific settings. The section name should start with a slash ``/'' and not end with a slash.

The [/SERVER/SHARE]

Section for share-specific settings. The section name should start with a slash followed by the server name followed by a slash ending on the share name. It should not end with a slash.

## EXPLANATION OF EACH PARAMETER
This chapter explains each possible option. The section names - specified between parentheses after each option - shows the applicable sections for this option. For example: ( [global] ) specifies that this option is only possible for the section [global].

ignore ( [/SERVER] )

Ignore this server. Possible values are: true, false, 1 and 0. Example: ignore = true

interval ( [global] )

Interval for scanning the network for shares. Value is a number that specifies the network scanning interval in minutes. If the value is smaller or equal to zero the network is not scanned. Example: interval = 20

password ( [global], [/SERVER], [/SERVER/SHARE] )

Password. Value is string containing the password. Example: password = secret

servers ( [ignore] )

Servers to ignore. Value is each server to ignore separated by a comma. Example: servers = SERVER1, SERVER2, SERVER3

showhiddenshares ( [global], [/SERVER] )

Show hidden shares. Possible values are: true, false, 1 and 0. Example: showhiddenshares = false

timeout ( [global] )

Connection timeout in seconds. A server after this timeout is considered offline. Values smaller than 2 seconds are ignored. Example: timeout = 10

username ( [global], [/SERVER], [/SERVER/SHARE] )

Username. Value is string containing the username. Example: username = johndoe

workgroups ( [ignore] )

Workgroups to ignore. Value is each workgroup to ignore separated by a comma. Example: workgroups = WORKGROUP1, WORKGROUP2

## EXAMPLE

```
; Global settings
[global]
; Default username and password
username=user
password=totallysecret
; List hidden shares
showhiddenshares=true
; Connection timeout in seconds
timeout = 10
;Interval for updating new shares in minutes
interval = 10
; Section for servers and/or workgroups to ignore
[ignore]
servers=SERVER,SERVER2,SERVER3
workgroups=WORKGROUP,WG2
; Share-specific settings
[/SERVER/SHARE]
username=john
password=doe
; Server-specific settings
[/SERVER]
username=jane
password=doe
showhiddenshares=true
ignore=true
```

## SEE ALSO
fusesmb(1)

## AUTHOR
Vincent Wagelaar <vincent@ricardis.tudelft.nl>.


fuzzel.ini

package: fuzzel

title: fuzzel.ini(5)

text:
# fuzzel.ini(5)

## NAME
fuzzel.ini - configuration file for fuzzel(1)

## DESCRIPTION
fuzzel uses the standard unix configuration format, with section based key/value pairs. The default section is usually unnamed, i.e. not prefixed with a [section]. However it can also be explicitly named [main], say if it needs to be reopened after any of the other sections.

fuzzel will search for a configuration file in the following locations, in this order:

•XDG_CONFIG_HOME/fuzzel/fuzzel.ini (defaulting to ~/.config/fuzzel/fuzzel.ini if unset)

•XDG_CONFIG_DIRS/fuzzel/fuzzel.ini (defaulting to /etc/xdg/fuzzel/fuzzel.ini if unset)

An example configuration file containing all options with their default value commented out will usually be installed to /etc/xdg/fuzzel/fuzzel.ini.

## SECTION: main
include

Absolute path to configuration file to import. The import file has its own section scope. I.e. the including configuration is still in the default section after the include, regardless of which section the included file ends in.

•The path must be an absolute path, or start with ~/.

•Multiple include directives are allowed, but only one path per directive.

•Nested imports are allowed.

Default: not set.

namespace

Namespace for the spawned layer shell surface. Useful for blocking fuzzel out from screencasts in your compositor if it shows sensitive information, such as passwords. Default: launcher

output

Output (monitor) to display on. You can list the available outputs with wlr-randr or with Sway using swaymsg -t get_outputs. Example: DP-1

Default: Not set-- let the compositor choose output.

font

Comma separated list of fonts to use, in fontconfig format. That is, a font name followed by a list of colon-separated options. Most noteworthy is :size=n, which is used to set the font size. Note that the font size is also affected by the dpi-aware option. See FONT CONFIG below for details. Examples:

•Dina:weight=bold:slant=italic

•Courier New:size=12

•Fantasque Sans Mono:fontfeatures=ss01

Default: monospace.

use-bold

Boolean. When set, fuzzel may use bold fonts. For example, for the currently selected item. Default: no

dpi-aware

auto, yes, or no. When set to yes, fonts are sized using the monitor's DPI, making a font of a given size have the same physical size, regardless of monitor.

In this mode, the monitor's scaling factor is ignored; doubling the scaling factor will not double the font size.

When set to no, the monitor's DPI is ignored. The font is instead sized using the monitor's scaling factor; doubling the scaling factor does double the font size.

Finally, if set to auto, fonts will be sized using the monitor's DPI if all monitors have a scaling factor of 1. If at least one monitor as a scaling factor larger than 1 (regardless of whether the fuzzel window is mapped on that monitor or not), fonts will be scaled using the scaling factor.

Note that this option typically does not work with bitmap fonts, which only contains a pre-defined set of sizes, and cannot be dynamically scaled. Whichever size (of the available ones) that best matches the DPI or scaling factor, will be used.

Also note that if the font size has been specified in pixels (:pixelsize=N, instead of :size=N), DPI scaling (dpi-aware=yes) will have no effect (the specified pixel size will be used as is). But, if the monitor's scaling factor is used to size the font (dpi-aware=no), the font's pixel size will be multiplied with the scaling factor.

Default: auto.

gamma-correct

Boolean. When enabled, fuzzel will do gamma-correct blending in linear color space. This is how font glyphs are supposed to be rendered, but since nearly no applications or toolkits are doing it on Linux, the result may not look like you are used to. Compared to the default (disabled), bright glyphs on a dark background will appear thicker, and dark glyphs on a light background will appear thinner.

FreeType can limit the effect of the latter, with a technique called stem darkening. It is only available for CFF fonts (OpenType, .otf) and disabled by default (in FreeType). You can enable it by setting the environment variable FREETYPE_PROPERTIES="cff:no-stem-darkening=0" before starting fuzzel.

Also be aware that many fonts have been developed on systems that do not do gamma-correct blending, and may therefore look thicker than intended when rendered with gamma-correct blending, since the font designer set the font weight based on incorrect rendering.

In order to represent colors faithfully, higher precision image buffers are required. For this reason, fuzzel uses 16-bit image buffers (instead of 8-bit) when gamma-correct blending is enabled.

It is not possible to enable gamma-correct blending in cairo enabled builds of fuzzel, since cairo does not support 16-bit image buffers.

placeholder

Text to display as placeholder in the input box. Default: empty.

prompt

String to use as input prompt. Note that trailing spaces are trimmed, unless the string is quoted. Default: "> ".

message

Message to display above the prompt. Can contain some informational message, or can be used for having your prompt be above the input instead of in front. Supports newlines. For details on how long lines are treated, see message-mode.

message-mode

One of wrap, and expand. wrap: any line that is longer than width is wrapped to the following line. Wraps on space boundaries if available, trimming leading spaces caused by truncation. If no space is available, the line is broken up after width characters.

expand: If the longest line in message is longer than width, make the dialogue box wider to accommodate message.

icon-theme

Icon theme. Note that the name is case sensitive. Default: default.

icons-enabled

Boolean. When enabled, application icons (from the selected icon-theme) will be rendered. Default: yes.

hide-before-typing

Boolean. When enabled, application list will be hidden until the first letter is typed. When the prompt is cleared again, the list will appear. Default: no.

fields

Comma separated list of XDG Desktop entry fields to match against. Even though fuzzel only displays the application names, matching can (and by default is) be done against other fields as well. Supported fields are:

•filename

•name

•generic

•exec

•categories

•keywords

•comment

"filename" is the ".desktop" file name.

Default: filename,name,generic.

password-character

Default character to use with the command line option --password. Note that this can be overridden on the command line, by explicitly specifying the character with --password=X. Default: *.

match-mode

One of exact, fzf and fuzzy. exact: what you type is matched exactly against each field in the fields list.

fzf: fzf-style matching, where substrings from what you have typed are matched against each field in the fields list.

fuzzy: levenshtein-based fuzzy matching of what you have typed against each field in the fields list.

Default: fzf

sort-result

Boolean. Whether to sort the result or not. Disabling sorting means no comparisons will be made between match results. I.e. launch count, match length, etc will be ignored. This effectively disables the cache (though, the cache is still updated on exit). Disabling this can improve search latency when searching very large data sets.

Default: yes

match-counter

Boolean. When enabled, the match count and total count is displayed on the right-hand side of the input prompt. Disabling the counter also improves performance when loading a very large number of dmenu entries from STDIN. Default: no.

filter-desktop

Boolean. Filter desktop files based on the value of XDG_CURRENT_DESKTOP. Default: no.

show-actions

Boolean. Some desktop files define "actions", in addition to the application itself. Examples are "new window", "preferences", etc. When this option is enabled, those actions will be listed by fuzzel. Default: no.

terminal

terminal command to use when launching 'terminal' programs. The command may contain the placeholder {cmd} which will be replaced with the actual command to be run. When {cmd} is present, the command is only substituted in those locations and is not appended at the end.

Examples:

•foot -a '{cmd}' -T '{cmd}' {cmd} sets app-id and title to the command name, then executes it

•xterm -e {cmd} executes the command in xterm

•xterm -e (no {cmd}) uses old behavior: appends command after terminal args

Default: $TERMINAL -e.

list-executables-in-path

Boolean. When enabled, the list will include executables from the PATH environment variable. Default: no.

launch-prefix

Prefix to add before argv of executed program. If set, fuzzel will pass desktop file metadata through environment variables:

•DESKTOP_ENTRY_ID (also exported as FUZZEL_DESKTOP_FILE_ID for backward compatibility)

•DESKTOP_ENTRY_PATH

•DESKTOP_ENTRY_NAME

•DESKTOP_ENTRY_COMMENT

•DESKTOP_ENTRY_NAME_L (Localized)

•DESKTOP_ENTRY_COMMENT_L (Localized)

•DESKTOP_ENTRY_ICON

And if launching an action: •DESKTOP_ENTRY_ACTION (Action identifier)

•DESKTOP_ENTRY_ACTION_NAME

•DESKTOP_ENTRY_ACTION_NAME_L (Localized)

•DESKTOP_ENTRY_ACTION_ICON

Default: not set.

anchor

Set window anchor, i.e. where on screen the window will be displayed. You can choose one from:

•top-left

•top

•top-right

•left

•center

•right

•bottom-left

•bottom

•bottom-right

Default: center

x-margin

Horizontal margin away from the anchor point in pixels. Default: 0. Note: this option has no effect when anchor=center, top or bottom.

y-margin

Vertical margin away from the anchor point in pixels. Default: 0. Note: this option has no effect when anchor=center, left or right.

lines

Number of matches to show. Default: 15.

hide-prompt

Boolean. When set, hides the prompt line, making the window smaller. Input is still accepted though the prompt line is not displayed. Cannot be used with prompt-only. Default: no.

minimal-lines

Boolean. Adjust the number of lines to display to the minimum of lines and the number of input lines. Only effective in dmenu mode. This allows fuzzel to size itself to the actual number of input lines rather than always showing the full lines rows. Default: no.

width

Window width, in characters. Margins and borders not included. For variable width fonts this is an estimate, as the exact number of characters that will fit depends on which characters are being displayed. Default: 30.

tabs

Number of spaces a tab is expanded to. Default: 8.

horizontal-pad

Horizontal padding, in pixels, between border and content. Default: 40.

vertical-pad

Vertical padding, in pixels, between border and content. Default: 8.

inner-pad

Vertical padding between prompt and match list, in pixels. Default: 0.

image-size-ratio

The ratio of the large image displayed when there are only a "few" matches, compared to the full window size. Set to 1 to disable the the large images. Default: 0.5.

line-height

Override line height from font metrics. Default: use font metrics.

letter-spacing

Additional letter spacing. Negative values are allowed. Default: 0.

layer

Which layer to render the fuzzel window on. Valid values are top and overlay. top renders above normal windows, but typically below fullscreen windows and lock screens.

overlay renders on top of both normal windows and fullscreen windows. Note that the order is undefined if several windows use the same layer. Since e.g. lock screens typically use overlay, that means fuzzel may or may not appear on top of a lock screen.

Default: overlay

keyboard-focus

Keyboard focusing mode, valid modes are exclusive and on-demand. exclusive locks keyboard focus to fuzzel, receiving all keyboard input until closed.

on-demand makes fuzzel focus like a regular window, allowing other windows to take keyboard focus by e.g. clicking on them. By default switching keyboard focus will immediately close fuzzel, using exit-on-keyboard-focus-loss=no allows interacting with other windows while fuzzel is open.

Default: exclusive

exit-on-keyboard-focus-loss

Boolean. If true, exit when the fuzzel window loses keyboard focus. Setting this to false can be useful on compositors where enabling "focus-follows-mouse" causes fuzzel to exit as soon as the mouse is moved over another window. Sway (<= 1.7) exhibits this behavior, for example.

Default: yes

render-workers

Number of threads to use for rendering. Set to 0 to disable multithreading. Default: the number of available logical CPUs (including SMT). Note that this is not always the best value. In some cases, the number of physical cores is better. In case you have a ridiculous amount of cores and/or threads, consider limiting the number of render-workers, since fuzzel cannot parallelize more than the number of displayed entries.

match-workers

Number of threads to use for matching. Set to 0 to disable multithreading. Default: the number of available logical CPUs (including SMT). Note that this is not always the best value. In some cases, the number of physical cores is better. In case you have a ridiculous amount of cores and/or threads, consider limiting the number of match-workers, since fuzzel cannot parallelize more than the number of available entries.

delayed-filter-ms

Time, in milliseconds, to delay refiltering when there are more matches than delayed-filter-limit. Default: 300.

delayed-filter-limit

When there are more matches than this, switch from immediate refiltering to delayed refiltering (see delayed-filter-ms). Default: 20000.

scaling-filter

Scaling filter to use when down scaling PNGs. One of none, nearest, bilinear, box, linear, cubic, lanczos2, lanczos3 and lanczos3-stretched. none, nearest and bilinear are the fastest options, but also have the worst looking results.

cubic, lanczos2, lanczos3 and lanczos3-stretched are the slowest options, with the best looking results.

box, and to some degree, linear, are in the middle, performance wise, while in most cases still being just as, or close to, as good as cubic and the lanczos filters.

Default: box

cache

Specify the default cache location. If unset, $XDG_CACHE_HOME/fuzzel will be used. Set to /dev/null to disable caching. Default: not set.

auto-select

Boolean. When one entry is left, automatically select it. Default: no.

enable-mouse

Boolean. Enable mouse input. Default: yes.

## SECTION: colors
All color values are in RGBA.

background

Background color. Default: fdf6e3ff.

text

Text (foreground) color of unselected entries. Default: 657b83ff.

message

Text (foreground) color of the message string. Default: 657b83ff.

prompt

Text (foreground) color of prompt character(s). Default: 586e75ff.

placeholder

Text (foreground) color of the placeholder string. Default: 93a1a1ff.

input

Text (foreground) color of input string. Default: 657b83ff.

match

Text (foreground) color of the matched substring. Default: cb4b16ff.

selection

Background color of the selected entry. Default: eee8d5ff.

selection-text

Text (foreground) color of the selected entry. Default: 586e75ff.

selection-match

Text (foreground) color of the matched substring of the selected entry. Default: cb4b16ff.

counter=HEX

The color of the match count stats printed at the right-hand side of the input prompt. See COLORS. Default: 93a1a1ff.

border

Border color. Default: 002b36ff.

## SECTION: border
width

Width of the border, in pixels. Default: 1.

radius

Amount of corner "roundness". Default: 10.

selection-radius

Amount of corner "roundness" for the selected entry. Default: 0.

## SECTION: dmenu
mode

One of text or index. Determines what fuzzel prints on stdout when an entry is selected: text prints the entry itself, index prints the index of the selected entry. Index values start at zero for the first entry. Default: text.

exit-immediately-if-empty

Boolean. If enabled, fuzzel will not run at all (i.e. it will not open a window, and will not print anything on stdout) if there's nothing on stdin. Default: no.

## SECTION: key-bindings
This section lets you override the default key bindings.

The general format is action=combo1...comboN. That is, each action may have one or more key combinations, space separated. Each combination is in the form mod1+mod2+key. The names of the modifiers and the key must be valid XKB key names.

Note that if Shift is one of the modifiers, the key must not be in upper case. For example, Control+Shift+V will never trigger, but Control+Shift+v will.

Note that Alt is usually called Mod1.

xkbcli interactive-wayland can be useful for finding keysym names.

A key combination can only be mapped to one action. Lets say you want to bind Control+k to next. Since this is the default shortcut for delete-line-forward, you must unmap the default binding. This can be done by setting action=none; e.g. delete-line-forward=none.

cancel

Quit fuzzel without executing anything. Default: Control+g Control+c Control+bracketleft Escape.

execute

Execute the currently selected entry. Or, in dmenu mode, print the selected entry on stdout. Default: Return KP_Enter Control+y.

execute-or-next

If there is a single match, execute it. Or, in dmenu mode, print the selected entry on stdout. If there are more than one match, select the next entry. Wraps around when the last entry has been reached. Default: Tab.

execute-input

Execute the raw input as is, regardless of whether it matches anything in the list or not. In dmenu mode, prints the selected entry on stdout instead. Default: Shift+Return Shift+KP_Enter.

cursor-left

Moves the cursor one character to the left. Default: Left Control+b.

cursor-left-word

Moves the cursor one word to the left. Default: Control+Left Mod1+b.

cursor-right

Moves the cursor one character to the right. Default: Right Control+f.

cursor-right-word

Moves the cursor one word to the right. Default: Control+Right Mod1+f.

cursor-home

Moves the cursor to the beginning of the input. Default: Home Control+a.

cursor-end

Moves the cursor to the end of the input. Default: End Control+e.

delete-line-backward

Deletes everything before the cursor. Default: Control+u.

delete-line-forward

Deletes everything after the cursor. Default: Control+k.

delete-line

Deletes the entire input. Default: Control+Shift+BackSpace.

delete-prev

Deletes the character before the cursor. Default: BackSpace Control+h.

delete-prev-word

Deletes the word before the cursor. Default: Mod1+BackSpace Control+BackSpace Control+w.

delete-next

Deletes the character after the cursor. Default: Delete.

delete-next-word

Deletes the word after the cursor. Default: Mod1+d Control+Delete.

insert-selected

Copies the selected entry to the prompt, replacing the current prompt. In application mode, the Exec line is inserted, and in dmenu mode the entry itself is used. Default: Control+Tab.

expunge

Removes the currently selected entry from the cache (of most commonly launched applications). Default: Shift+Delete.

clipboard-paste

Pastes from the clipbard. Default: Control+v XF86Paste.

primary-paste

Pastes from the primary selection. This action is also bound to the middle mouse button (this is currently not configurable). Default: Shift+Insert Shift+KP_Insert.

prev

Select the previous entry. Does not wrap around when the first entry has been reached. Default: Up Control+p.

prev-with-wrap

Select the previous entry. Wraps around when the first entry has been reached. Default: ISO_Left_Tap. (Shift+Tab)

prev-page

Switch to the previous page. Default: PageUp KP_PageUp.

next

Select the next entry. Does not wrap around when the last entry has been reached. Default: Down Control+n.

next-with-wrap

Select the next entry. Wraps around when the last entry has been reached. Default: unbound.

next-page

Switch to the next page. Default: Page_Down KP_Page_Down.

first

Select the first entry, on the first page. Default: Control+Home.

last

Select the last entry, on the last page. Default: Control+End.

custom-1, custom-2, ..., custom-19

Execute the currently selected entry, then exit with a non-zero exit code. custom-1 exits with exit code 10, custom-2 with 11, custom-3 with 12, and so on. Default:

•custom-1: Mod1+1

•custom-2: Mod1+2

•custom-3: Mod1+3

•custom-4: Mod1+4

•custom-5: Mod1+5

•custom-6: Mod1+6

•custom-7: Mod1+7

•custom-8: Mod1+8

•custom-9: Mod1+9

•custom-10: Mod1+10

•custom-11: Mod1+11

•custom-12: Mod1+12

•custom-13: Mod1+13

•custom-14: Mod1+14

•custom-15: Mod1+15

•custom-16: Mod1+16

•custom-17: Mod1+17

•custom-18: Mod1+18

•custom-19: Mod1+19

## FONT CONFIG
Fontconfig uses a flexible string format for specifying fonts that allows you to define font families, styles, weights, and various properties. The basic syntax follows this pattern:

"Family Name:style=Style:weight=Weight:size=Size"

Common Properties:

•family - Font family name

•style - italic, oblique, roman

•weight - light, normal, bold, black (or numeric values 100-900)

•size - Point size

•slant - italic, oblique, roman

•width - condensed, normal, expanded

Fontconfig supports fallback fonts. You can specify multiple font families separated by commas. The fallback fonts are searched in the order they appear. If a glyph cannot be found in any of the fallback fonts, the dynamic fallback list from fontconfig (for the primary font) is searched. Ex:

"My Custom Font, DejaVu Sans:weight=bold, sans-serif"

Fontconfig always returns something unless you don't have any fonts installed, regardless of what font name you give it. You can check fonts that would be matched with `fc-match -s YourFontName`.

The font library Fuzzel uses, fcft, will search the explicit fallbacks whenever a glyph cannot be found in the primary font. When it cannot find a glyph in the explicit fallbacks, then it searches the fontconfig fallbacks of the first font in Fuzzel's list.

This design allows a custom fallback sequence as well as custom font options for each fallback.

## SEE ALSO
•fuzzel(1)

•https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html

•https://codeberg.org/dnkl/fuzzel


fwupd-remotes.d

package: fwupd

title: fwupd-remotes.d(5)

summary: remotes used for the fwupd daemon.

text:
# fwupd-remotes.d(5)

## NAME
fwupd-remotes.d - remotes used for the fwupd daemon.

## SYNOPSIS
The /etc/fwupd/remotes.d and /var/fwupd/remotes.d directories are used to read information about remote metadata sources. The complete description of the file format and possible parameters are documented here for reference purposes.

## FILE FORMAT
The file consists of a multiple sections with optional parameters. Parameters are of the form:

```

```

```
[section]
```

```
key = value
```

The file is line-based, each newline-terminated line represents either a comment, a section name or a parameter.

Section and parameter names are case sensitive.

Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is discarded as is leading and trailing whitespace in a parameter value. Internal whitespace within a parameter value is retained.

Any line beginning with a hash (#) character is ignored, as are lines containing only whitespace.

The values following the equals sign in parameters are all either a string (no quotes needed), unsigned integers, or a boolean, which may be given as true or false. Case is not significant in boolean values, but is preserved in string values.

For per-user credential storage, the remote Username and Password can also be stored in XDG_CONFIG_HOME rather than in /etc, for example in ~/.config/fwupd/remotes.d/lvfs-embargo.conf.

## REMOTE PARAMETERS
The [fwupd Remote] section can contain the following parameters:

Enabled=false

If the remote should be considered when finding releases for devices. Only enabled remotes are refreshed when using fwupdmgr refresh and when considering what updates are available for each device. This value can be modified using fwupdmgr enable-remote.

Title=

The single line description to show in any UI tools.

MetadataURI=

The URL of AppStream metadata to download and use. This should have a suffix of .xml.gz for legacy metadata and .xml.xz for the more modern format. Only prefixes of http://, https:// and file:// are supported here.

FirmwareBaseURI=

The optional base URL of the cabinet archives to download. If not specified the MetadataURI base URL is used. Only prefixes of http://, https:// and file:// are supported here.

ApprovalRequired=false

If set to true then only releases allow-listed with fwupdmgr set-approved-firmware will show in CLI and GUI tools.

ReportURI=

The endpoint to use for sending success reports for firmware obtained from this remote, or blank to disable this feature.

AutomaticReports=false

If true, automatically sent success reports for firmware obtained from this remote after the firmware update has completed.

AutomaticSecurityReports=false

If true, automatically sent HSI platform security reports when running fwupdmgr security.

NoPhasedUpdates=false

If true, disregard the requirement check for random client phased deployment.

A systems eligibility to a phased update is determined by seeding random number generator with /etc/machine-id, the archive filename, and the remote cache mtime. If the seed divides by the metadata-provided phased_update value with no remainder then the release is considered. This also implies that the seed will be different on a different machine, for a different update or if the metadata is refreshed.

OrderBefore=

This remote will be ordered before any remotes listed here, using commas as the delimiter.

NOTE: When the same firmware release is available from multiple remotes, the one with the highest priority will be used.

OrderAfter=

This remote will be ordered after any remotes listed here, using commas as the delimiter.

Username=

The username to use for BASIC authentication when downloading metadata and firmware from this remote, and for uploading success reports.

Password=

The password (although, in practice this will be a user *token*) to use for BASIC authentication when downloading both metadata and firmware from this remote, and for uploading success reports.

RefreshInterval=

The time in seconds after which the front end tools should re-download the metadata signature, or 0 to re-download every time.

## NOTES
The basename of the path without the extension is used for the remote ID. For instance, the /etc/fwupd/remotes.d/lvfs.conf remote file will have ID of lvfs.

## SEE ALSO
<fwupd.conf(5)>


fwupd.conf

title: fwupd.conf(5)

text:
# fwupd.conf(5)

## NAME
fwupd.conf - configuration file for the fwupd daemon.

## SYNOPSIS
The /etc/fwupd/fwupd.conf file is the main configuration file for the fwupd daemon. The complete description of the file format and possible parameters are documented here for reference purposes.

## FILE FORMAT
The file consists of a multiple sections with optional parameters. Parameters are of the form:

```

```

```
[section]
```

```
key = value
```

The file is line-based, each newline-terminated line represents either a comment, a section name or a parameter.

Section and parameter names are case sensitive.

Only the first equals sign in a parameter is significant. Whitespace before or after the first equals sign is discarded as is leading and trailing whitespace in a parameter value. Internal whitespace within a parameter value is retained.

Any line beginning with a hash (#) character is ignored, as are lines containing only whitespace.

The values following the equals sign in parameters are all either a string (no quotes needed), unsigned integers, or a boolean, which may be given as true or false. Case is not significant in boolean values, but is preserved in string values.

## DAEMON PARAMETERS
The [fwupd] section can contain the following parameters:

DisabledDevices=

Allow blocking specific devices by their GUID, using semicolons as delimiter.

DisabledPlugins=

Allow blocking specific plugins by name. Use fwupdmgr get-plugins to get the list of plugins.

ArchiveSizeMax=

Maximum archive size that can be loaded in Mb, with 25% of the total system memory as the default.

IdleTimeout=300

Idle time in seconds to shut down the daemon, where a value of 0 specifies “never”.

NOTE: some plugins might inhibit the auto-shutdown, for instance thunderbolt.

IdleInhibitStartupThreshold=500

If the daemon takes more than this time to startup (in milliseconds) then inhibit the idle shutdown timer. A value of 0 specifies “never”.

VerboseDomains=

Comma separated list of domains to log in verbose mode. If unset, no domains are set to verbose. If set to “*”, all domains are verbose, which is the same as running the daemon with --verbose --verbose.

UpdateMotd=true

Update the message of the day (MOTD) on device and metadata changes.

EnumerateAllDevices=false

For some plugins, enumerate only devices supported by metadata.

ApprovedFirmware=

A list of firmware checksums that has been approved by the site admin If unset, all firmware is approved.

UriSchemes=file;https;http;ipfs

Allowed URI schemes in the preference order; failed downloads from the first scheme will be retried with the next in order until no choices remain.

IgnorePower=false

Ignore power levels of devices when running updates.

IgnoreRequirements=false

Ignore some device requirements, for instance removing the generic GUID requirement of a CHID, child, parent or sibling. This is not recommended for production systems, although it may be useful for firmware development.

IgnoreEfivarsFreeSpace=false

Ignore the efivars free space requirement for db, dbx, KEK and PK updates. This may be required on Linux kernels older than 6.4, or where the hardware does not support UEFI RT->QueryVariableInfo.

OnlyTrustPostQuantumSignatures=false

Only trust post-quantum cryptographic signatures. This is only recommended when you are sure the firmware contains a valid PQ signature.

OnlyTrusted=true

Only support installing firmware signed with a trusted key. Do not set this to false on a production or trusted system.

ShowDevicePrivate=true

Show data such as device serial numbers which some users may consider private.

TrustedUids=

UIDs matching these values that call the D-Bus interface should marked as trusted.

HostBkc=

Comma separated list of best known configuration IDs to be used when using fwupdmgr sync. This can downgrade firmware to factory versions or upgrade firmware to a supported config level. e.g. vendor-factory-2021q1,mycompany-2023

ReleaseDedupe=true

Deduplicate duplicate releases by the archive checksum are available from more than one source.

ReleasePriority=local

When the same version release is available from more than one source this option can be used to either prefer the local version (avoiding a potentially expensive download) or to prefer the remote version (which may have updated metadata such as release notes).

The possible options are local or remote or empty to not make any adjustment to the policy, relying on the OrderAfter and OrderBefore sections in the remote.

EspLocation=

Set the preferred location used for the EFI system partition (ESP) path. This is typically used if UDisks was not able to automatically identify the location for any reason.

RequireImmutableEnumeration=false

Don't allow fwupd plugins to directly interact with devices during probe or setup stages. The kernel should provide all device information in sysfs files or udev properties. This will block some plugins from working.

Manufacturer=

ProductName=

ProductSku=

Family=

EnclosureKind=

BaseboardProduct=

BaseboardManufacturer=

Override values for SMBIOS or Device Tree data on the local system. These are only required when the SMBIOS or Device Tree data is invalid, missing, or to simulate running on another system. Empty values should be used to populate blank entries or add values to populate specific entries.

TrustedReports=VendorId=$OEM

Vendor reports matching these expressions will have releases marked as trusted-report. Each *OR* section is delimited by a ; and each *AND* section delimited by &, e.g.

•

DistroId=chromeos

Any report uploaded from ChromeOS is trusted.

•

DistroId=chromeos&RemoteId=lvfs

Any report found in the lvfs remote uploaded from a ChromeOS machine is trusted.

•

DistroId=fedora&VendorId=19

Any report uploaded from Fedora 19 is trusted.

•

DistroId=fedora&VendorId=$OEM

Any report uploaded from Fedora by the hardware OEM is trusted.

•

DistroId=fedora;DistroId=rhel&DistroVersion=9

Any report uploaded from Fedora (any version) or from RHEL 9 is trusted.

NOTE: a VendorId of $OEM represents the OEM vendor ID of the vendor that owns the firmware, for example, where Lenovo QA has generated a signed report for a Lenovo laptop.

There are also three os-release values available, $ID, $VERSION_ID and $VARIANT_ID, which allow expressions like:

•

DistroId=$ID

•

DistroId=$ID,DistroVersion=$VERSION_ID

•

Flags=is-upgrade,from-oem

Any flags listed here must all be matched by the report.

P2pPolicy=metadata

This tells the daemon what peer-to-peer policy to use. For instance, using Passim, an optional local caching service. Using peer-to-peer data might reduce the amount of bandwidth used on your network considerably.

There are three possible values:

•

nothing: Do not publish any files

•

metadata: Only publish shared metadata that is common to each machine.

•

firmware: Only publish firmware archives after the next reboot of the machine.

At some point in the future fwupd will change the default to metadata,firmware.

TestDevices=false

Create virtual test devices and remote for validating daemon flows. This is only intended for CI testing and development purposes.

## UEFI_CAPSULE PARAMETERS
The [uefi_capsule] section can contain the following parameters:

EnableGrubChainLoad=false

Configure GRUB to launch fwupdx64.efi instead of using other methods such as NVRAM or Capsule-On-Disk.

DisableShimForSecureBoot=false

The shim loader is required to chainload the fwupd EFI binary unless the fwupd.efi file has been self-signed manually.

RequireESPFreeSpace=0

Amount of free space required on the ESP, for example using 32 for 32Mb. By default this is dynamically set to at least twice the size of the payload.

DisableCapsuleUpdateOnDisk=false

Allow ignoring the CapsuleOnDisk support advertised by the firmware.

EnableEfiDebugging=false

Enable the low-level debugging of fwupdx64.efi to the FWUPDATE_DEBUG_LOG EFI variable.

NOTE: enabling this option is going to fill up the NVRAM store much more quickly and should only be enabled when debugging an issue with the EFI binary.

This value also has no affect when using Capsule-on-Disk as the EFI helper binary is not being used.

RebootCleanup=true

Delete any capsule files copy to the ESP, and remove any EFI variables set for the update.

NOTE: disabling this option is only required when debugging the flash process and normal users should not need to change this setting.

ScreenWidth=0

Override the screen width in pixels of the EFI framebuffer as used by the UX capsule.

ScreenHeight=0

Override the screen height in pixels of the EFI framebuffer as used by the UX capsule.

## UEFI_DB PARAMETERS
The [uefi_db] section can contain the following parameters:

UpdateWindowsCA=false

The flash space used by UEFI updates is limited -- if we update the Windows CA (when we're not dual-booted with Windows) then we are using the flash space we need for UEFI db and dbx updates.

This setting forces the Windows UEFI certificate to be updatable even if Microsoft Windows is not detected.

## MSR PARAMETERS
The [msr] section can contain the following parameter:

MinimumSmeKernelVersion=5.18.0

Minimum kernel version required for reliable AMD SME detection via the SYSCFG MSR.

This only needs to be modified by enterprise kernels that have cherry picked the feature into a kernel with an old version number.

## REDFISH PARAMETERS
The [redfish] section can contain the following parameters:

Uri=

The URI to the Redfish service in the format scheme://ip:port for instance https://192.168.0.133:443

Username=

The username to use when connecting to the Redfish service.

Password=

The password to use when connecting to the Redfish service.

BearerToken=

The bearer token to use for authenticating to the Redfish service.

CACheck=false

Whether to verify the server certificate or not. This is turned off by default. BMCs using self-signed certificates will not work unless the plugin does not verify it against the system CAs.

IpmiDisableCreateUser=false

Do not use IPMI KCS to create an initial user account if no SMBIOS data. Setting this to true prevents creating user accounts on the BMC automatically.

ManagerResetTimeout=1800

Amount of time in seconds to wait for a BMC restart.

## THUNDERBOLT PARAMETERS
The [thunderbolt] section can contain the following parameters:

MinimumKernelVersion=4.13.0

Minimum kernel version to allow use of this plugin.

This only needs to be modified by enterprise kernels that have cherry picked the feature into a kernel with an old version number.

DelayedActivation=false

Forces delaying activation until shutdown/logout/reboot.

## DELL_KESTREL PARAMETERS
The [dell_kestrel] section can contain the following parameters:

UpdateOnDisconnect=true

Delaying firmware activation until the dock cable is unplugged.

## TEST PARAMETERS
The [test] section can contain the following parameters:

AnotherWriteRequired=false

Do two passes of the write function.

CompositeChild=false

If the device should have a child device.

DecompressDelay=0

Delay in milliseconds to use when decompressing the test device.

NeedsActivation=false

If the device needs activating before deploying the update.

NeedsReboot=false

If the device needs a reboot before deploying the update.

RegistrationSupported=

If the device should register with other plugins.

RequestDelay=10

Delay in milliseconds to use when requesting user input from the user.

RequestSupported=false

If the device interactive request is supported.

VerifyDelay=0

Delay in milliseconds to use when verifying the test device.

WriteDelay=0

Delay in milliseconds to use when writing the test device.

WriteSupported=

If the device write is supported. If unsupported the device write will not start.

## NOTES
/etc/fwupd/fwupd.conf may contain either hardcoded or autogenerated credentials and must only be readable by the user that is running the fwupd process, which is typically root.

## SEE ALSO
<fwupdmgr(1)> <fwupd-remotes.d(5)>


gammu-backup

package: gammu

title: gammu-backup(5)

summary: gammu(1) backup file format.

text:
# gammu-backup(5)

## NAME
gammu-backup - gammu(1) backup file format.

The backup format is text file encoded in either ASCII or UCS-2-BE encodings.

This file use ini file syntax, see ini.

## EXAMPLES
If you will backup settings to Gammu text file, it will be possible to edit it. It's easy: many things in this file will be written double - once in Unicode, once in ASCII. When you will remove Unicode version Gammu will use ASCII on restore (and you can easy edit ASCII text) and will convert it according to your OS locale. When will be available Unicode version of text, it will be used instead of ASCII (useful with Unicode phones - it isn't important, what locale is set in computer and no conversion Unicode -> ASCII and ASCII -> Unicode is done).

You can use any editor with regular expressions function to edit backup text file. Examples of such editors can be vim or TextPad which both do support regular expressions.

Remove info about voice tags

Find:

```
^Entry\([0-9][0-9]\)VoiceTag = \(.*\)\n
```

Replace:

```
<blank>
```

Change all numbers starting from +3620, +3630, +3660, +3670 to +3620

Find:

```
Type = NumberGeneral\nEntry\([0-9][0-9]\)Text = "\+36\(20\|30\|60\|70\)\n
```

Replace:

```
Type = NumberMobile\nEntry\1Text = "\+3620
```

Change phone numbers type to mobile for numbers starting from +3620, +3630,... and removing the corresponding TextUnicode line

Find:

```
Type = NumberGeneral\nEntry\([0-9][0-9]\)Text = "\+36\([2367]0\)\([^\"]*\)"\nEntry\([0-9][0-9]\)TextUnicode = \([^\n]*\)\n
```

Replace:

```
Type = NumberMobile\nEntry\1Text = "\+36\2\3"\n
```

SEE ALSO:

converting-formats

## AUTHOR
Michal Čihař <michal@cihar.com>

## COPYRIGHT
2009-2015, Michal Čihař <michal@cihar.com>


gammu-smsbackup

title: gammu-smsbackup(5)

summary: gammu(1) SMS backup file format.

text:
# gammu-smsbackup(5)

## NAME
gammu-smsbackup - gammu(1) SMS backup file format.

The SMS backup format is text file encoded in current encoding of platform where Gammu is running.

This file use ini file syntax, see ini.

## SECTIONS
The file consists of sections, whose name starts with SMSBackup. When creating the backup file, three digits are appended to this text defining order. While reading the backup, any part after SMSBackup text is ignored and everything which begins with this is processed. So you can as well give the section name SMSBackupFoo and it will be processed.

The number of messages in backup file is currently limited by GSM_BACKUP_MAX_SMS (100000 at time of writing this document).

### SMSBackup section
Each section interprets one physical SMS message (eg. one message part in case of multipart messages).

### Decoded text
For SMS backups created by Gammu, there is a decoded text as a comment just after the section name:

```
[SMSBackup001]
; This is message text
```

The text can be split to more lines if it is too long or of original message included new lines.

NOTE:

This is easiest way to get message text, however also the least reliable one, because it is stored in the comments in the file.

### Variables
The following variables can be defined for each SMS:

SMSC

Text representation of SMSC number, not used by Gammu if SMSCUnicode exists.

SMSCUnicode

Hex encoded UCS-2 string with SMSC number.

Class

Message class.

Sent

Timestamp, when message has been sent.

PDU

Message type, one of:

- Deliver - received message

- Submit - message to send

- Status_Report - message to send with delivery report

DateTime

Timestamp of message (sent or received).

RejectDuplicates

Whether receiver should reject duplicates.

ReplaceMessage

ID of message to replace.

MessageReference

Message reference number as generated by network.

State

State of the message:

- Read

- UnRead

- Sent

- UnSent

Number

Recipient number.

Name

Name of the message.

Length

Length of message text.

Coding

Coding of the message:

- 8bit - binary message

- Default - GSM encoding, up to 160 chars in message

- Unicode - Unicode encoding, up to 70 chars in message

Text00 ... TextNN

Numbered parts of the message payload.

Folder

ID of folder where the message was saved.

UDH

User defined header of the message.

## EXAMPLE
The backup of message can look like following:

```
[SMSBackup000]
#ABCDEFGHIJKLMNOPQRSTUVWXYZ
#
SMSC = "+4540590000"
SMSCUnicode = 002B0034003500340030003500390030003000300030
Sent = 20021201T025023
State = UnRead
Number = "+4522706947"
NumberUnicode = 002B0034003500320032003700300036003900340037
Name = ""
NameUnicode =
Text00 = 004100420043004400450046004700480049004A004B004C004D004E004F0050005100520053005400550056005700580059005A000A
Coding = Default
Folder = 1
Length = 27
Class = -1
ReplySMSC = False
RejectDuplicates = True
ReplaceMessage = 0
MessageReference = 0
```

## AUTHOR
Michal Čihař <michal@cihar.com>

## COPYRIGHT
2009-2015, Michal Čihař <michal@cihar.com>