ctags-json-output

package: universal-ctags

title: ctags-json-output(5)

summary: JSON based ctags output

text:
# ctags-json-output(5)

## NAME
ctags-json-output - JSON based ctags output

## SYNOPSIS

```
ctags --output-format=json ...
```

## DESCRIPTION
Universal Ctags supports JSON <https://www.json.org/>

(strictly speaking JSON Lines <https://jsonlines.org/> ) output format if the ctags executable is built with libjansson. JSON output goes to standard output by default.

## FORMAT
Each JSON line represents a tag.

```
$ ctags --extras=+p --output-format=json --fields=-s input.py
{"_type": "ptag", "name": "JSON_OUTPUT_VERSION", "path": "1.0", "pattern": "in development"}
{"_type": "ptag", "name": "TAG_FILE_SORTED", "path": "1", "pattern": "0=unsorted, 1=sorted, 2=foldcase"}
...
{"_type": "tag", "name": "Klass", "path": "/tmp/input.py", "pattern": "/^class Klass:$/", "language": "Python", "kind": "class"}
{"_type": "tag", "name": "method", "path": "/tmp/input.py", "pattern": "/^    def method(self):$/", "language": "Python", "kind": "member", "scope": "Klass", "scopeKind": "class"}
...
```

A key not starting with _ is mapped to a field of ctags. "--output-format=json --list-fields" options list the fields.

A key starting with _ represents meta information of the JSON line. Currently only _type key is used. If the value for the key is tag, the JSON line represents a regular tag. If the value is ptag, the line represents a pseudo-tag.

The output format can be changed in the future. JSON_OUTPUT_VERSION pseudo-tag provides a change client-tools to handle the changes. Current version is "1.0". A client-tool can extract the version with path key from the pseudo-tag.

The JSON output format is newly designed and has no limitation found in the default tags file format.

- The values for kind key are represented in long-name flags. No one-letter is here.

- Scope names and scope kinds have distinguished keys: scope and scopeKind. They are combined in the default tags file format.

## DATA TYPE USED IN A FIELD
Values for the most of all keys are represented in JSON string type. However, some of them are represented in string, integer, and/or boolean type.

"--output-format=json --list-fields" options show What kind of data type used in a field of JSON.

```
$ ctags --output-format=json --list-fields
#LETTER NAME           ENABLED LANGUAGE         JSTYPE FIXED DESCRIPTION
F       input          yes     NONE             s--    no    input file
...
P       pattern        yes     NONE             s-b    no    pattern
...
f       file           yes     NONE             --b    no    File-restricted scoping
...
e       end            no      NONE             -i-    no    end lines of various items
...
```

JSTYPE column shows the data types.

's'

string

'i'

integer

'b'

boolean (true or false)

For an example, the value for pattern field of ctags takes a string or a boolean value.

## VERSIONS

### Change since "0.0"
•

New key kindName for TAG_ROLE_DESCRIPTION pseudo tag kindName is added to store the name of the kind in TAG_ROLE_DESCRIPTION pseudo tags.

In 0.0, a "TAG_ROLE_DESCRIPTION" pseudo tag was printed like:

```
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",

                  "parserName": "LANG!KIND", }
```

In 1.0, it is printed like:

```
{"_type": "ptag", "name": "TAG_ROLE_DESCRIPTION",

                  "parserName": "LANG",

                  "kindName": "KIND",  }
```

## SEE ALSO
ctags(1), tags(5), ctags-client-tools(7)

branch: sisyphus


tags

title: tags(5)

text:
# tags(5)

## NAME
tags - Vi tags file format extended in ctags projects

## DESCRIPTION
The contents of next section is a copy of FORMAT file in Exuberant Ctags source code in its subversion repository at sourceforge.net.

Exceptions introduced in Universal Ctags are explained inline with "EXCEPTION" marker. Statements that are made further clear in Universal Ctags are explained inline with "COMMENT" marker.

----

## PROPOSAL FOR EXTENDED VI TAGS FILE FORMAT

```
Version: 0.06 DRAFT
Date: 1998 Feb 8
Author: Bram Moolenaar <Bram at vim.org> and Darren Hiebert <dhiebert at users.sourceforge.net>
```

### Introduction
The file format for the "tags" file, as used by Vi and many of its descendants, has limited capabilities.

This additional functionality is desired:

1.

Static or local tags. The scope of these tags is the file where they are defined. The same tag can appear in several files, without really being a duplicate.

2.

Duplicate tags. Allow the same tag to occur more then once. They can be located in a different file and/or have a different command.

3.

Support for C++. A tag is not only specified by its name, but also by the context (the class name).

4.

Future extension. When even more additional functionality is desired, it must be possible to add this later, without breaking programs that don't support it.

### From proposal to standard
To make this proposal into a standard for tags files, it needs to be supported by most people working on versions of Vi, ctags, etc.. Currently this standard is supported by:

Darren Hiebert <dhiebert at users.sourceforge.net>

Exuberant Ctags

Bram Moolenaar <Bram at vim.org>

Vim (Vi IMproved)

These have been or will be asked to support this standard:

Nvi

Keith Bostic <bostic at bsdi.com>

Vile

Tom E. Dickey <dickey at clark.net>

NEdit

Mark Edel <edel at ltx.com>

CRiSP

Paul Fox <fox at crisp.demon.co.uk>

Lemmy

James Iuliano <jai at accessone.com>

Zeus

Jussi Jumppanen <jussij at ca.com.au>

Elvis

Steve Kirkendall <kirkenda at cs.pdx.edu>

FTE

Marko Macek <Marko.Macek at snet.fri.uni-lj.si>

### Backwards compatibility
A tags file that is generated in the new format should still be usable by Vi. This makes it possible to distribute tags files that are usable by all versions and descendants of Vi.

This restricts the format to what Vi can handle. The format is:

1.

The tags file is a list of lines, each line in the format:

```
{tagname}<Tab>{tagfile}<Tab>{tagaddress}
```

{tagname}

Any identifier, not containing white space.. EXCEPTION: Universal Ctags violates this item of the proposal; tagname may contain spaces. However, tabs are not allowed.

<Tab>

Exactly one TAB character (although many versions of Vi can handle any amount of white space).

{tagfile}

The name of the file where {tagname} is defined, relative to the current directory (or location of the tags file?).

{tagaddress}

Any Ex command. When executed, it behaves like 'magic' was not set.

2.

The tags file is sorted on {tagname}. This allows for a binary search in the file.

3.

Duplicate tags are allowed, but which one is actually used is unpredictable (because of the binary search).

The best way to add extra text to the line for the new functionality, without breaking it for Vi, is to put a comment in the {tagaddress}. This gives the freedom to use any text, and should work in any traditional Vi implementation.

For example, when the old tags file contains:

```
main    main.c  /^main(argc, argv)$/
DEBUG   defines.c       89
```

The new lines can be:

```
main    main.c  /^main(argc, argv)$/;"any additional text
DEBUG   defines.c       89;"any additional text
```

Note that the ';' is required to put the cursor in the right line, and then the '"' is recognized as the start of a comment.

For Posix compliant Vi versions this will NOT work, since only a line number or a search command is recognized. I hope Posix can be adjusted. Nvi suffers from this.

### Security
Vi allows the use of any Ex command in a tags file. This has the potential of a trojan horse security leak.

The proposal is to allow only Ex commands that position the cursor in a single file. Other commands, like editing another file, quitting the editor, changing a file or writing a file, are not allowed. It is therefore logical to call the command a tagaddress.

Specifically, these two Ex commands are allowed:

•

A decimal line number:

```
89
```

•

A search command. It is a regular expression pattern, as used by Vi, enclosed in // or ??:

```
/^int c;$/
?main()?
```

There are two combinations possible:

•

Concatenation of the above, with ';' in between. The meaning is that the first line number or search command is used, the cursor is positioned in that line, and then the second search command is used (a line number would not be useful). This can be done multiple times. This is useful when the information in a single line is not unique, and the search needs to start in a specified line.

```
/struct xyz {/;/int count;/
389;/struct foo/;/char *s;/
```

•

A trailing comment can be added, starting with ';"' (two characters: semi-colon and double-quote). This is used below.

```
89;" foo bar
```

This might be extended in the future. What is currently missing is a way to position the cursor in a certain column.

### Goals
Now the usage of the comment text has to be defined. The following is aimed at:

1.

Keep the text short, because:

- The line length that Vi can handle is limited to 512 characters.

- Tags files can contain thousands of tags. I have seen tags files of several Mbytes.

- More text makes searching slower.

2.

Keep the text readable, because:

- It is often necessary to check the output of a new ctags program.

- Be able to edit the file by hand.

- Make it easier to write a program to produce or parse the file.

3.

Don't use special characters, because:

•

It should be possible to treat a tags file like any normal text file.

### Proposal
Use a comment after the {tagaddress} field. The format would be:

```
{tagname}<Tab>{tagfile}<Tab>{tagaddress}[;"<Tab>{tagfield}..]
```

{tagname}

Any identifier, not containing white space.. EXCEPTION: Universal Ctags violates this item of the proposal; name may contain spaces. However, tabs are not allowed. Conversion, for some characters including <Tab> in the "value", explained in the last of this section is applied.

<Tab>

Exactly one TAB character (although many versions of Vi can handle any amount of white space).

{tagfile}

The name of the file where {tagname} is defined, relative to the current directory (or location of the tags file?).

{tagaddress}

Any Ex command. When executed, it behaves like 'magic' was not set. It may be restricted to a line number or a search pattern (Posix). COMMENT: {tagaddress} could contain tab characters. See ctags-client-tools(7) to know how to programmatically extract {tagaddress} (called "pattern field" there) and parse it.

Optionally:

;"

semicolon + doublequote: Ends the tagaddress in way that looks like the start of a comment to Vi.

{tagfield}

See below.

A tagfield has a name, a colon, and a value: "name:value".

- The name consist only out of alphabetical characters. Upper and lower case are allowed. Lower case is recommended. Case matters ("kind:" and "Kind: are different tagfields). EXCEPTION: Universal Ctags allows users to use a numerical character in the name other than its initial letter.

- The value may be empty. It cannot contain a <Tab>.

- When a value contains a \t, this stands for a <Tab>.

- When a value contains a \r, this stands for a <CR>.

- When a value contains a \n, this stands for a <NL>.

- When a value contains a \\, this stands for a single \ character.

Other use of the backslash character is reserved for future expansion. Warning: When a tagfield value holds an MS-DOS file name, the backslashes must be doubled!

EXCEPTION: Universal Ctags introduces more conversion rules.

- When a value contains a \a, this stands for a <BEL> (0x07).

- When a value contains a \b, this stands for a <BS> (0x08).

- When a value contains a \v, this stands for a <VT> (0x0b).

- When a value contains a \f, this stands for a <FF> (0x0c).

- The characters in range 0x01 to 0x1F included, and 0x7F are converted to \x prefixed hexadecimal number if the characters are not handled in the above "value" rules.

EXCEPTION: Universal Ctags allows all these escape sequences in {tagname} and {tagfile} also. However, about {tagfile}, a condition must be satisfied. See "Exceptions in Universal Ctags" about the condition.

•

The leading space (0x20) and ! (0x21) in {tagname} are converted to \x prefixed hexadecimal number (\x20 and \x21) if the tag is not a pseudo-tag. As described later, a pseudo-tag starts with !. These rules are for distinguishing pseudo-tags and non pseudo-tags (regular tags) when tags lines in a tag file are sorted.

Proposed tagfield names:

FIELD-NAME

DESCRIPTION

arity

Number of arguments for a function tag.

class

Name of the class for which this tag is a member or method.

enum

Name of the enumeration in which this tag is an enumerator.

file

Static (local) tag, with a scope of the specified file. When the value is empty, {tagfile} is used.

function

Function in which this tag is defined. Useful for local variables (and functions). When functions nest (e.g., in Pascal), the function names are concatenated, separated with '/', so it looks like a path.

kind

Kind of tag. The value depends on the language. For C and C++ these kinds are recommended: 0.0 c class name d define (from #define XXX) e enumerator f function or method name F file name g enumeration name m member (of structure or class data) p function prototype s structure name t typedef u union name v variable 168u When this field is omitted, the kind of tag is undefined.

struct

Name of the struct in which this tag is a member.

union

Name of the union in which this tag is a member.

Note that these are mostly for C and C++. When tags programs are written for other languages, this list should be extended to include the used field names. This will help users to be independent of the tags program used.

Examples:

```
asdf    sub.cc  /^asdf()$/;"    new_field:some\svalue   file:
foo_t   sub.h   /^typedef foo_t$/;"     kind:t
func3   sub.p   /^func3()$/;"   function:/func1/func2   file:
getflag sub.c   /^getflag(arg)$/;"      kind:f  file:
inc     sub.cc  /^inc()$/;"     file: class:PipeBuf
```

The name of the "kind:" field can be omitted. This is to reduce the size of the tags file by about 15%. A program reading the tags file can recognize the "kind:" field by the missing ':'. Examples:

```
foo_t   sub.h   /^typedef foo_t$/;"     t
getflag sub.c   /^getflag(arg)$/;"      f       file:
```

Additional remarks:

•

When a tagfield appears twice in a tag line, only the last one is used.

Note about line separators:

Vi traditionally runs on Unix systems, where the line separator is a single linefeed character <NL>. On MS-DOS and compatible systems <CR><NL> is the standard line separator. To increase portability, this line separator is also supported.

On the Macintosh a single <CR> is used for line separator. Supporting this on Unix systems causes problems, because most fgets() implementation don't see the <CR> as a line separator. Therefore the support for a <CR> as line separator is limited to the Macintosh.

Summary:

line separator

generated on

accepted on

<LF>

Unix

Unix, MS-DOS, Macintosh

<CR>

Macintosh

Macintosh

<CR><LF>

MS-DOS

Unix, MS-DOS, Macintosh

The characters <CR> and <LF> cannot be used inside a tag line. This is not mentioned elsewhere (because it's obvious).

Note about white space:

Vi allowed any white space to separate the tagname from the tagfile, and the filename from the tagaddress. This would need to be allowed for backwards compatibility. However, all known programs that generate tags use a single <Tab> to separate fields.

There is a problem for using file names with embedded white space in the tagfile field. To work around this, the same special characters could be used as in the new fields, for example \s. But, unfortunately, in MS-DOS the backslash character is used to separate file names. The file name c:\vim\sap contains \s, but this is not a <Space>. The number of backslashes could be doubled, but that will add a lot of characters, and make parsing the tags file slower and clumsy.

To avoid these problems, we will only allow a <Tab> to separate fields, and not support a file name or tagname that contains a <Tab> character. This means that we are not 100% Vi compatible. However, there is no known tags program that uses something else than a <Tab> to separate the fields. Only when a user typed the tags file himself, or made his own program to generate a tags file, we could run into problems. To solve this, the tags file should be filtered, to replace the arbitrary white space with a single <Tab>. This Vi command can be used:

```
:%s/^\([^ ^I]*\)[ ^I]*\([^ ^I]*\)[ ^I]*/\1^I\2^I/
```

(replace ^I with a real <Tab>).

COMMENT: Universal Ctags running on MS Windows converts the \ separator to / by default, and allows the escape sequences even in {tagfile} if a condition is satisfied. See "Exceptions in Universal Ctags" about the condition.

TAG FILE INFORMATION:

Pseudo-tag lines can be used to encode information into the tag file regarding details about its content (e.g. have the tags been sorted?, are the optional tagfields present?), and regarding the program used to generate the tag file. This information can be used both to optimize use of the tag file (e.g. enable/disable binary searching) and provide general information (what version of the generator was used).

The names of the tags used in these lines may be suitably chosen to ensure that when sorted, they will always be located near the first lines of the tag file. The use of "!_TAG_" is recommended. Note that a rare tag like "!" can sort to before these lines. The program reading the tags file should be smart enough to skip over these tags.

The lines described below have been chosen to convey a select set of information.

Tag lines providing information about the content of the tag file:

```
!_TAG_FILE_FORMAT   {version-number}        /optional comment/
!_TAG_FILE_SORTED   {0|1}                   /0=unsorted, 1=sorted/
```

The {version-number} used in the tag file format line reserves the value of "1" for tag files complying with the original UNIX vi/ctags format, and reserves the value "2" for tag files complying with this proposal. This value may be used to determine if the extended features described in this proposal are present.

Tag lines providing information about the program used to generate the tag file, and provided solely for documentation purposes:

```
!_TAG_PROGRAM_AUTHOR        {author-name}   /{email-address}/
!_TAG_PROGRAM_NAME  {program-name}  /optional comment/
!_TAG_PROGRAM_URL   {URL}   /optional comment/
!_TAG_PROGRAM_VERSION       {version-id}    /optional comment/
```

EXCEPTION: Universal Ctags introduces more kinds of pseudo-tags. See ctags-client-tools(7) about them.

COMMENT: Though pseudo-tags are semantically different from regular tags, They use the same format, which is:

```
{tagname}<Tab>{tagfile}<Tab>{tagaddress}
```

, and the escape sequences and illegal characters explained in "Proposal" section also applies to pseudo-tags.

----

## EXCEPTIONS IN UNIVERSAL CTAGS
Universal Ctags supports this proposal with some exceptions.

### Exceptions
1.

{tagname} in tags file generated by Universal Ctags may contain spaces and several escape sequences. Parsers for documents like Tex and reStructuredText, or liberal languages such as JavaScript need these exceptions. See {tagname} of Proposal section for more detail about the conversion.

2.

{tagfile} in tags file generated by Universal Ctags may contain spaces and several escape sequences if \ characters are not used as filename separators. UNIX-like systems use / for the purpose. On MS Windows, Universal Ctags converts \ in filenames to / by default. So, generally this condition is satisfied. Universal Ctags emits several pseudo tags telling whether the condition is satisfied or not. See ctags-client-tools(7) about these pseudo tags.

3.

"name" part of {tagfield} in a tag generated by Universal Ctags may contain numeric characters, but the first character of the "name" must be alphabetic.

### Compatible output and weakness
Default behavior (--output-format=u-ctags option) has the exceptions. On the other hand, with --output-format=e-ctags option ctags has no exception; Universal Ctags command may use the same file format as Exuberant Ctags. However, --output-format=e-ctags throws away a tag entry which name includes a space or a tab character. TAG_OUTPUT_MODE pseudo-tag tells which format is used when ctags generating tags file.

## SEE ALSO
ctags(1), ctags-client-tools(7), ctags-incompatibilities(7), readtags(1)


odbc.ini

package: unixODBC

title: odbc.ini(5)

text:
# odbc.ini(5)

## NAME
/etc/odbc.ini, $HOME/.odbc.ini - unixODBC data source configuration files

## DESCRIPTION
/etc/odbc.ini is a system-wide configuration file for ODBC Data Source Names (DSNs).

$HOME/.odbc.ini is a user-specific configuration file for ODBC Data Source Names (DSNs).

Paths to both configuration files can be overridden by unixODBC build options. Call odbcinst -j to determine the default configuration file paths on your system.

## NOTES

### Templates
Many ODBC drivers come with .ini file templates. Using odbcinst to install these templates is recommended.

### FILE FORMAT
odbc.ini follows the pesudo-standard ini file syntax convention of one or more [section headings], each followed by zero or more key = value attributes.

[ODBC Data Sources] section

This mandatory section lists each data source name (DSN) as a key. The associated values serve as comments. Each entry must be matched by an ini file [section] describing the data source.

Data Source Name [section]

Each data source is identified by a [section header], which is the DSN name used by applications. Each DSN definition section may contain values for the keys:

• Driver (REQUIRED)

The name of the ODBC driver to use for the DSN. The name must exactly match the [section name] of the driver definition stored in odbcinst.ini (and listed by odbcinst -q -d).

• Description

Human-readable data source description.

• Database

Database name or identifier. The meaning is driver-specific and can specify a file path, Unix socket path, an identifier relative to a server name, etc.

• Servername

Server name. The meaning is driver-specific but generally specifies a DNS name, IP network address or driver-specific discovery identifier.

For a full list of supported parameters, refer to the HTML-formatted "Administrator Manual" shipped with unixODBC, the documentation for your ODBC driver and any data-source templates supplied by your driver.

## EXAMPLES
An example odbc.ini configuration file is shown in the "Administrator Manual" shipped with unixODBC.

## SEE ALSO
unixODBC(7), odbcinst(1), isql(1), iusql(1), odbcinst.ini(5)

"The unixODBC Administrator Manual (HTML)"

## AUTHORS
The authors of unixODBC are Peter Harvey <pharvey@codebydesign.com> and Nick Gorham <nick@lurcher.org>.

For a full list of contributors, refer to the AUTHORS file.

## COPYRIGHT
unixODBC is licensed under the GNU Lesser General Public License. For details about the license, see the COPYING file.


odbcinst.ini

title: odbcinst.ini(5)

text:
# odbcinst.ini(5)

## NAME
/etc/odbcinst.ini - unixODBC driver configuration file

## DESCRIPTION
/etc/odbcinst.ini is a configuration file for unixODBC drivers.

The file can be updated by using the odbcinst utility (recommended) or edited by hand.

## FILE FORMAT
The general .ini file format is:

```
[SectionName1]
key1 = value1
key2 = value2
...
[SectionName2]
key1 = value1
key2 = value2
...
```

Each ODBC driver has its own section and can be referred to by the name of that section in files such as odbc.ini. Within each section, unixODBC also recognises the following configuration keys:

Description

A text string briefly describing the driver.

Driver

A filesystem path to the actual driver library.

Setup

A filesystem path to the driver setup library.

FileUsage

The section named [ODBC] configures global options. Keys recognised in the [ODBC] section include:

Trace

Enable ODBC driver trace output, which is written to the file path specified by TraceFile. Some ODBC drivers have their own trace control options. Unlike the Trace option, these separate options are usually specified at the Data Source Name (DSN) level.

Trace will be enabled if the corresponding value contains any case variant of "1", "y", "yes" or "on".

TraceFile

Specifies the system path or path-pattern to which ODBC driver trace output will be written. This option has no effect unless Trace is enabled. The default file location for trace output is /tmp/sql.log. WARNING: Setting TraceFile to a path writable by multiple users might not work correctly, as only the first user will be able to create and open the file.

## TEMPLATE FILES
Many ODBC drivers come with .ini file templates, which can be installed by using the odbcinst utility.

Template files use the same format as odbcinst.ini.

## EXAMPLES
To install the unixODBC PostgreSQL driver, the following configuration can be entered into odbcinst.ini:

```
[PostgreSQL]
Description = PostgreSQL driver for GNU/Linux
Driver      = /usr/lib/psqlodbcw.so
Setup       = /usr/lib/libodbcpsqlS.so
FileUsage   = 1
```

Driver paths can vary, depending on your operating system and whether your distribution is multi-arch enabled. Some drivers also require Driver64 and Setup64 entries.

The above section can be referenced in odbc.ini as follows:

```
Driver = PostgreSQL
```

The recommended way of adding the PostgreSQL driver to your system is by creating a template file containing:

```
[PostgreSQL]
Description = PostgreSQL driver for GNU/Linux
Driver      = /usr/lib/psqlodbcw.so
Setup       = /usr/lib/libodbcpsqlS.so
```

and calling odbcinst as follows:

\# odbcinst -i -d -f template.ini

## SEE ALSO
unixODBC(7), odbcinst(1), odbc.ini(5)

"The unixODBC Administrator Manual (HTML)"

## AUTHORS
The authors of unixODBC are Peter Harvey <pharvey@codebydesign.com> and Nick Gorham <nick@lurcher.org>.

For a full list of contributors, refer to the AUTHORS file.

## COPYRIGHT
unixODBC is licensed under the GNU Lesser General Public License. For details about the license, see the COPYING file.


title: unl0kr.conf(5)

text:
# unl0kr.conf(5)

## NAME
UNL0KR - configuration file

## DESCRIPTION
UNL0KR expects a configuration file with options in the following format, with one option/value pair per line:

```
[section]
<option>=<value>
```

On launch, UNL0KR searches for configuration files in various locations and successively merges all files together into a single configuration. Files are searched for and, if found, merged in the following order:

- /usr/share/unl0kr/unl0kr.conf

- /usr/share/unl0kr/unl0kr.conf.d/ (alphabetically)

- /etc/unl0kr.conf

- /etc/unl0kr.conf.d/ (alphabetically)

- Override files (in supplied order)

## OPTIONS

### General
animations = <true|false>

Enable or disable animations. Useful for slower devices. Default: false.

backend = <fbdev|drm>

The rendering backend to use. Default: fbdev.

timeout = <value>

The time in seconds before unl0kr will consider the entry a failure and shutdown. Setting timeout to 0 disables this feature. Default: 0.

### Keyboard
autohide = <true|false>

Whether to automatically hide the keyboard when a hardware keyboard is detected on launch. Default: true.

layout = <us|de|fr|...>

The default layout to use. Can be changed from the UI at runtime. The available options are defined by the available keyboards at build time. Default: us.

popovers = <true|false>

Enable or disable key press popovers showing the selected key. default: true.

### Textarea
obscured = <true|false>

Whether the password in the text entry box can be read. Selectable in the UI at runtime. Default: true.

bullet = <value>

The character that will be used to obscure the password. Default: bullet.

### Theme
default = <adwaita-light|adwaita-dark|breezy-light|breezy-dark|nord-light|nord-dark|pmos-light|pmos-dark>

Selects the default theme on boot. Can be changed at runtime to the alternative theme. Default: breezy-dark.

alternative = <breezy-light|breezy-dark|pmos-light|pmos-dark>

Selects the alternative theme which the user can then choose on boot. Default: breezy-light.

### Input
keyboard = <true|false>

Enable or disable the use of hardware keyboards. Default: true

pointer = <true|false>

Enable or disable the use of a hardware mouse or other pointing device. Default: true.

touchscreen = <true|false>

Enable or disable the use of the touchscreen. Default: true.

### Quirks
fbdev_force_refresh = <true|false>

If true and using the framebuffer backend, this triggers a display refresh after every draw operation. This has a negative performance impact. Default: false.

terminal_prevent_graphics_mode = <true|false>

If true, this avoids setting the terminal into graphics mode. This will show the terminal command prompt. Default: false.

terminal_allow_keyboard_input = <true|false>

If true, this avoids turning off terminal keyboard input. This will show your password on the terminal. Default: false.

## SEE ALSO
unl0kr(1)

## AUTHORS
Undef <debian@undef.tools> Johannes Marbach <n0-0ne@mailbox.org>


upmpdcli.conf

package: upmpdcli

title: upmpdcli.conf(5)

summary: upmpdcli.conf documentation

text:
# upmpdcli.conf(5)

## NAME
upmpdcli.conf - upmpdcli.conf documentation

## DESCRIPTION
upmpdcli.conf is the configuration file for upmpdcli(1). Its location must be indicated to the program either through the UPMPD_CONFIG environment variable or through the -c command line option.

Each line in the configuration file contains a setting name and its value, e.g.:

logfilename = /tmp/upmpdcli.log

Almost all configuration variables have suitable defaults, and the program distribution includes a sample file, typically installed to /etc, where variables are listed and commented.

You should have a look at the online manual for more complete information: http://www.lesbonscomptes.com/upmpdcli/upmpdcli-manual.html

## PARAMETERS
logfilename = fn

Log file name. Defaults to stderr. This can also be specified as -d logfilename. Some plugins use different files or stderr to log their messages to.

loglevel = int

Log level. Can also be specified as -l loglevel. Some plugins have their own settings that control log verbosity.

upnplogfilename = fn

Enable low level libnpupnp logging and set output name. Set to empty for stderr. This log is not active if this variable is not set at all. Use an empty value for the messages to go to stderr.

upnploglevel = int

Log level for the low level UPnP lib. For historical reasons the matching values are 1 less than equivalent values for the upmpdcli log. 4 is very verbose.

pkgdatadir = dfn

XML and other constant data storage directory. Default: '$prefix/share/upmpdcli' (e.g.: '/usr/share/upmpdcli').

pidfile = fn

Name of the lock file used to store the current process pid. Only used if the process is launched by user root. Used by the init system, and to avoid multiple instances. The only reason to change the value is if you actually want to have several instances running (also change cachedir in this case).

upnpiface = cstr

Network interface(s) to use for UPnP. This can be left empty to use the first found suitable interface, or set to a single "*" character for using all interfaces. Else set it to a space-separated list of interface names (use double quotes if the names have embedded space characters).

upnpip = string

IP V4 address to use for UPnP, alternative to using an interface name.

upnpport = int

Port number used for UPnP. libupnp/pupnp defaults to using the first free port after 49152. Note that clients do not need to know about the value, which is automatically discovered.

useipv6 = bool

Enable use of IPV6. By default we only use IPV4.

friendlyname = string

"Friendly Name" for the Media Renderer. This will be displayed by most Control Points to identify the Renderer. Some OpenHome Control Points may display the 'ohproductroom' value instead.

avfriendlyname = string

Specific friendly name for the UPnP/AV Media Renderer. The default is to append "-av" to the friendlyname value.

upnpav = bool

Enable UPnP AV services (0/1). This is set by default, but it may useful to switch it off to avoid cluttering the Renderer choices if you only use OpenHome.

openhome = bool

Enable OpenHome services (0/1). This defaults to 1, as OpenHome queuing is superior for most usages. There should be little reason to turn it off.

lumincompat = bool

Disable the OpenHome Credentials service. At some point, this was necessary to enable Lumin to see upmpdcli instances: for some unknown reason, Lumin 1.10 did not discover upmpdcli with Credentials enabled.

ohinfotexttodata = bool

Store metadata into the OpenHome "metatext" variable. The OpenHome Info service are supposed to hold different data, mostly for radios, with permanent radio data (icon, url, radio name) set in the "Metadata" variable, and information about the current title recorded in the "Metatext" variable. Setting this option will have upmpdcli store any non-empty Metatext data in the Metadata variable. This will help some players display the album art for the current title (e.g. Kazoo).

checkcontentformat = bool

Check that input format is supported. Extract the protocolinfo information from the input metadata and check it against our supported formats. Set this option to 0 if a control point or media server sends good audio data with bad metadata.

iconpath = fn

Path to the Renderer icon. The image will be displayed by Control Points which support it. The UPnP protocol has provisions for a renderer to send the URL to a descriptive icon as part of the device description. Due to current (and probably permanent) *upmpdcli* limitations, the image file *must* be a 64x64 32 bits-per-pixel png file. Default: '$pkgdatadir/icon.png'. The icon will only be read once, when upmpdcli starts up.

saveohcredentials = bool

Save the streaming services login parameters to disk. This allows sharing the password with the upmpdcli media server streaming service proxy, if you are also using it. Avoids having to enter the password in the regular configuration file. Depending on your situation, you may see this as a security risk. The default is true, because I don't see this as a real issue in the general case.

opensslcmd = fn

Path to the openssl command The OHCredentials service needs openssl 1.1.x or newer. Path to the openssl command to use if the system one (in /usr/bin) is too old. Not set by default.

cachedir = dfn

Directory used to store cached data Only used for the OpenHome queue metadata for now. The default value is ~/.cache/upmpdcli for normal users or /var/cache/upmpdcli when upmpdcli is started as root.

presentationhtml = fn

Path to the presentation HTML document You can change it to replace the default presentation page. The page will only be read once, when upmpdcli starts up. It can't presently be used for status updates (but I guess that you could put a redirect in there, to something more dynamic served by a real HTTP server). Default: '$pkgdatadir/presentation.html'.

enablel16 = bool

Advertise L16 format support L16 is a raw linear 16 bits audio stream and the source of many issues because it does not include identifying information. It used to be disabled by default, because of an mpd bug resulting in a lot of noise. It's now on by default, but can still be disabled if needed. It seems that it sometimes interfers badly with the win10 "cast to device" feature, so you may try to turn it off if you have problems with this.

mpdhost = string

Host MPD runs on. Defaults to localhost. This can also be specified as -h host

mpdport = int

IP port used by MPD Can also be specified as -p port. Defaults to the normal MPD port, 6600

mpdpassword = string

MPD password. Password for connecting to MPD (only necessary if password access is enabled in the MPD configuration file).

mpdtimeoutms = int

MPD connection timeout in milliseconds. If this is not zero, dialogs with mpd will timeout after the value. This will allow upmpdcli to stay responsive (return errors) if MPD ever becomes stuck.

ownqueue = bool

Set if we own the MPD queue. If this is set (on by default), we own the MPD queue and will fearlessly clear it. Can also be specified as -q 0|1.

onstart = fn

Command to run when playback is about to begin. Specify the full path to the program, e.g. /usr/bin/logger.

onplay = fn

Command to run when MPD state switches to "PLAY". Specify the full path to the program, e.g. /usr/bin/logger.

onpause = fn

Command to run when MPD state switches to "PAUSE". Specify the full path to the program, e.g. /usr/bin/logger.

onstop = fn

Command to run when MPD state switches to "STOP". Specify the full path to the program, e.g. /usr/bin/logger.

onstandby = fn

Command to run when the setstandby action is called. Specify the full path to the program. It is called with one 0/1 argument to change the standby state (1 for activating standby), and with no argument to query the state. In all cases, it should print the standby state (0/1) to stdout before exiting.

externalvolumecontrol = fn

Use external command to manage the the sound volume (0/1). This is used in the case where MPD is unable to control the volume, but some other command can, for example if you have an external amp on which it is possible to set and read the volume through scripts. If set, the calls to MPD to set and read the volume will be replaced by executions of 'onvolumechange' and 'getexternalvolume'

getexternalvolume = fn

Command to run for reading the sound volume. The command should write a 0-100 numeric value to stdout.

onvolumechange = fn

Command to run to set the volume. Used when 'externalvolumecontrol' is set. Specify the full path to the program, which is called with the volume as the first argument, e.g. /some/script 85.

avtautoplay = string

Automatically fake a Play command when track is set. The UPnP/AV SetAVTransportURI, used to set the track to play, normally does not change the current transport state: an explicit Play command is required to start playing if the transport was stopped. Setting this parameter will synthetize a Play command after receiving SetAVTransportURI. This is needed by some control points which do not send the Play command.

ohproductroom = string

The name of the room where the Product is located. Set to "Main Room" by default, displayed in place of the "friendly name" by some control points. ProductRoom is used to group the Product with other related Products in the same physical room (e.g. a source with a pre-amp). Products which are physically linked must always share the same ProductRoom name.

radiolist = fn

Path to an external file with radio definitions. Radio stations can be defined in this file (main configuration file), or in an external file (or both). Using an external file can ease distribution to multiple machines, makes things clearer and is now the default. See the distributed file (name below) for information on how to define a radio station. In case you want to define radios in the main configuration file, they MUST occur at the end of the file (because they are defined as subsections, the last of which extends to the end of the file).

radioscripts = fn

Radio metadata scripts directory. Path of a directory where the scripts used for fetching the channel metadata are located. The default is /usr/share/upmpdcli/radio_scripts. Note that the scripts are always first looked for in the locations defined by $PATH.

ohmanufacturername = string

Manufacturer name.

ohmanufacturerinfo = string

Manufacturer information.

ohmanufacturerurl = string

URL for manufacturer web site.

ohmanufacturerimageuri = string

Uri for manufacturer's logo.

ohmodelname = string

Model name.

ohmodelinfo = string

Model information.

ohmodelurl = string

URL for model web site.

ohmodelimageuri = string

Uri for model's icon.

ohproductname = string

User-visible product name. By default this is set to ModelName.

ohproductinfo = string

Product information.

ohproducturl = string

URL for product web site. This may be the UPnP presentation page.

ohproductimageuri = string

Uri for product image.

ohmetapersist = bool

Save queue metadata to disk (0/1). This allows persistence of the metadata information across restarts, the default is 1, and there is no reason to turn it off.

ohmetasleep = int

Mimimum interval (Seconds) between two cache saves. Increasing this may improve playlist load speed on a slow device. The default is to start a new save as soon as the previous one is done (if the list changed again inbetween).

msfriendlyname = string

Friendly name for the Media Server (if enabled). The default is to append "-mediaserver" to the friendlyname value.

msrootalias = string

Media Server root alias Object ID. Use the specified Media Server container as root. The Control Point will directly show this container when connecting, which will avoid having to skip over the top levels if you don't use them. (E.g. the active plugin list if there is only one plugin). The value is an UPnP object ID, which is unfortunately not generally obtainable from Control Points. However the commonly useful values are simple: - `0$uprcl$` Direct access to the Local Media root - `0$uprcl$folders` Direct access to the Local Media [folders] tree. An alias must begin with `0` (which is the mandatory UPnP root object ID), followed by `$pluginname$` where _pluginname_ could be any subdirectory of `/usr/share/upmpdcli/cdplugins` except `pycommon` (e.g. `uprcl`, `qobuz`, `upradios`...), and the rest would depend on the plugin type.

plgmicrohttphost = string

Hostname/IP address used in proxy URLs. The default is to use the same host/address as the UPnP server. Using localhost/127.0.0.1 instead loses the ability to stream to a remote renderer, but allows for portable playlists.

plgmicrohttpport = int

IP port for Subsonic, Tidal, or Qobuz local HTTP service. The URLs for tracks streamed from these services point to a local microhttpd HTTP server running on this port. It uses redirection to the actual service URL, or proxying from it, during streaming. The default is 49149.

plgproxymethod = string

Decide if we proxy (copy from the service to the renderer), or redirect the streaming services streams. This setting is related to response handling from a streaming service, e.g. Subsonic, Tidal, or Qobuz. The URLs, that these services offer, are usually short-lived, therefore they can't be part of a playlist. upmpdcli hides these resources behind a stable URL that is presented to the renderer (player). With the "redirect" default setting, the stable URL becomes an HTTP 302 redirection, pointing to the original streaming resource. The renderer has to resolve this redirection and then can stream from the original location. Some renderers, e.g. AV receivers, are not able to follow an HTTP redirection.

With the "proxy" setting, the original URL remains concealed and there's no redirection. upmpdcli reads the music from the remote service, and serves it to the renderer in parallel. It requires more resources compared to the redirection and is less efficient, but some renderers do not support HTTP redirection.

msiconpath = fn

Path to the Media Server icon. The image will be displayed by Control Points which support it. Due to current (and probably permanent) *upmpdcli* limitations, the image file *must* be a 64x64 32 bits-per-pixel png file. Default: '$pkgdatadir/icon.png'. The icon will only be read once, when upmpdcli starts up.

webserverdocumentroot = string

Path from which the UPnP HTTP server will serve files: 0:none, 1:auto, abs. path: use it. Some Mediaserver plugins need it, e.g. for serving icon files or cached data. The default value is 1, resulting into an actual path of /var/cache/upmpdcli/www or ~/.cache/upmpdcli/www.

hrauser = string

Hra user name. Your Hra login name.

hrapass = string

Hra password. The password for your Hra account.

hralang = string

Hra language setting (en/de). Some Highresaudio messages will be set in the appropriate language.

hratitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

qobuzuser = string

Qobuz user name. value may be bogus Your Qobuz login name. This must be set to activate the Media Server plugin but the actual value is not used.

qobuzformatid = cstr

Qobuz stream quality. 5 for mp3/320, 6 for FLAC, 7 FLAC 24/96, 27 for hi-res (if your subscription allows streaming each of the formats).

qobuzrenumtracks = bool

Qobuz track renumbering. Renumber tracks by counting elements, avoiding issues with Kodi. Enabled by default.

qobuzexplicititemnumbers = bool

Explicit item numbers in brackets. Add item numbers in square brackes in lists, mostly for kodi compatibility/usability. Disabled by default.

qobuzprependartisttoalbum = bool

Artist name before albums in album lists. Prepend artist to album in album lists, mostly for kodi compatibility/usability. Disabled by default.

qobuztitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

tidaluser = string

Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

tidaltokentype = string

Oath2 authentication token type. The type of token used for OAUTH2 authentication, typically Bearer.

tidalaudioquality = cstr

Tidal maximum stream quality. LOW for mp3/96, HIGH for mp3/320, LOSSLESS for FLAC 16/44, HI_RES for FLAC up to 24/48, HI_RES_LOSSLESS for hi-res FLAC files (if your subscription allows streaming each of the formats).

tidaltitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

tidalprependnumberinitemlist = bool

Use item numbers in album lists for kodi compatibility Kodi always tries to sort things, with this parameter we force it to show the entries in the desired order.

tidalenableimagecaching = bool

Enables image caching, requires webdocumentroot Allows the plugin to cache images for Artists and Albums, requires webdocumentroot and some disk space, recommended

tidalsearchlimit = int

Tidal search limit Set the maximum numbers of items returned by search, defaults to 15

tidaloverridecountrycode = string

Override the country code. This will allow you to specify the desired two-letter country code. When not specified, it should default to the country code of the profile.

tidaltrackidregex = string

Track id regex expression. The expression used to validate the track_id in trackuri. Do not set it unless you know what you are doing.

tidalverboselogging = bool

Enables verbose logging, defaults to 0 (no) Enables more verbose logging, might be useful for testing

uprcluser = string

Bogus user name variable. Used for consistency with other Media Server plugins to decide if the service should be started (so, do set it if you want a Media Server). You probably also want to set uprclautostart=1 so that initialisation starts as soon as the program does.

uprcltitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

uprclmediadirs = string

Media directories This is a space-separated list of directories to explore for music files. This is used directly as the recoll "topdirs" value, so you can use double-quote quoting for paths with embedded spaces. If not set, we will try to use contentDirs from the Minim config. An error will occur if both are empty.

uprclnoradioconf = bool

Don't make the local radio list as a playlist. By default, uprcl will process the local radio list and make it available as a playlist (in the Playlists top container). This can slow down the initialisation and is useless if the upradios plugin is also running, so you can disable it with this variable.

uprclhostport = string

Uprcl HTTP server host and port for serving media files. Uprcl uses a separate HTTP server based on the Python Bottle framework and Waitress server. The HTTP server will listen on this address and port, which will also be inserted on the URLs we produce. If the variable is not set, we will use port 9090 and the same address as the server used for other services (either plgmicrohttphost or the first ipv4 address used by the upnp layer. not. Example: 192.168.1.1:9090. As it is reasonable to use the same address as the upnp layer, see also uprclport for just specifying the port.

uprclport = string

Uprcl HTTP server port for serving media files. Port to use for listening for media requests. The listen address will be either plgmicrohttphost if it is set, or the first ipv4 address used by the upnp layer. Ignored if uprclhostport is set.

uprclconfdir = dfn

uprcl Recoll index directory This is usually not defined and defaults to /var/cache/upmpdcli/uprcl. The name is a bit misleading because there is little real configuration data in there: it's mostly programmatically generated from actual configuration found elsewhere (but also see uprclconfrecolluser).

uprclconfrecolluser = fn

Name of the user Recoll config additions file This is the name of a file with additional parameters for the uprcl recoll.conf file, to which the contents will be appended before indexing. The default is /var/cache/upmpdcli/uprcl/recoll.conf.user. If set, should be an absolute path.

uprclminimconfig = fn

Name of the Minim Server configuration file If set, this is the name of a Minim Server configuration file from which we should fetch parameters like aliasTags, etc. (See the manual). Not set by default, and optional.

uprclnotagview = bool

Suppress folder "Tag View" entries. The "Tag View" entry allow browsing a subdirectory by tags. It can be quite useful but also a problem with some Control Points, or kinds of usage.

uprclnoindexing = bool

Do not run the indexer on startup. Mostly for gaining time when restarting the server for debugging.

upradiosuser = string

Bogus user name variable. Used for consistency with other Media Server plugins to decide if the service should be started (so, do set it if you want to see the radio list).

upradiostitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

upradiosmaxthreads = int

Maximum number of threads to use while initializing the radio list Most radios are defined by playlist files which may need several network interactions before the actual URL usable by the control point can be reached. We use multiple threads to speed up this process, this is the maximum thread count.

radio-browseruser = string

Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

radio-browsertitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

radio-browseripinfotoken = string

IPInfo token. Set your ipinfo token in order to have the shortcut to the local radios.

radio-browsercountry = string

The preferred country. Set this to the preferred country in order to have the shortcut to the local radios. This is alternative to using the ipinfo token. The values is to be specified in the form of a country code, e.g. `FR`, `IT`, etc.

radio-paradiseuser = string

Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

radio-paradisetitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

mother-earth-radiouser = string

Bogus user name variable. Decides if the service should be started. Set it to any arbitrary value.

mother-earth-radiotitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

subsonicuser = string

SubSonic User name. Decides if the service should be started. Set it to the appropriate user name.

subsonicpassword = string

SubSonic Password. Required for SubSonic authentication. Set it to the appropriate password.

subsoniclegacyauth = bool

SubSonic legacy authentication mode. Required for SubSonic authentication with some servers (e.g. lms). Set to 1 to enable.

subsonicuseragent = string

SubSonic user agent. Lets you specify the user agent in http requests, defaults to upmpdcli.

subsonicskipuseragent = bool

Force user agent to be empty. You might want to enable this one in case the default user agent causes some trouble. YMMV.

subsonicbaseurl = string

SubSonic server base url. URL of the server, without the port. Specify http or https

subsonicport = int

SubSonic server port. The port of the SubSonic server

subsonicserverpath = string

SubSonic server path. Optional, use only if the server is exposed on a specific path

subsonicitemsperpage = int

SubSonic items per page Number of items per page for SubSonic

subsoniccachetimeoutartists = int

SubSonic cache timeout for artists Cache timeout for artists, defaults to 600

subsonicappendyeartoalbumcontainer = bool

Append year to album container If enabled, the year will be appended to the album as a container. Enabled by default.

subsonicappendyeartoalbumview = bool

Append year to album view If enabled, the year will be appended to the album view. Disabled by default.

subsonicappendyeartoalbumsearchres = bool

Append year to album as search result If enabled, the year will be appended to the album as a search result. Disabled by default.

subsonicappendrolestoartist = bool

Append roles to artists If enabled, the artist roles will be appended to artist entries. Enabled by default.

subsonictranscodecodec = string

Enable transcoding If a value is set, it will be used as the codec for the transcoding process. The value should be the file extension of the desired format (without the leading dot), e.g. "mp3" or "flac" as this will provide the ground for communicating the correct MIME type to the renderer. This is a free-form text that's used in the communication between the Subsonic server (e.g. Navidrome) and upmpdcli. The server must have the corresponding entry for this format value to start the assigned transcoding command.

Transcoding doesn't happen for files that are already in the required format.

subsonictranscodemaxbitrate = int

Set max bitrate for transcoding If a value is set, it will be used as the max bitrate for the transcoding process

subsonicserversidescrobbling = bool

Enable server-side scrobbling If enabled, we will scrobble the song when streaming starts. Disabled by default.

subsonicprependnumberinalbumlist = bool

Add a progressive number to album in album lists. Mostly for Kodi compatibility and usability. Enabled by default.

subsonictaginitialpageenabledir = bool

Subsonic enable Internet Radios Enables Internet Radios. Disabled by default, upmpdcli offers multiple ways of handling Internet Radios

subsonicshowemptyfavorites = bool

Subsonic show empty Favorites entries Force entries for Favorites, even if there are no Favorites, disabled by default

subsonicshowemptyplaylists = bool

Subsonic show empty Playlists entry Force entry for Playlists, even if there are no Playlists, disabled by default

subsonictitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

subsonicallowappendgenreinalbumview = bool

Subsonic show genres in album view Show Genres in album view, disabled by defaults

subsonicallowgenreinalbumcontainer = bool

Subsonic show genres in album container entry Show Genres in album container, used in album lists, disabled by defaults

subsonicenableimagecaching = bool

Enables image caching, requires webdocumentroot Allows the plugin to cache images from the server, requires webdocumentroot and some disk space, recommended

subsonicenablecachedimageagelimit = bool

Enables pruning for image cache, requires webdocumentroot Allows the plugin to remove old cache images from the server, recommended

subsoniccachedimagemaxagedays = int

Age limit for image files in image cache in days Sets the maximum image file age in days, relevant when pruning is enabled

subsonicallowartistcoverart = bool

Enables use of cover art from artists, enabled by default Set it to `0` in order to avoid to use coverArt from artists, which can be expensive/slow against Navidrome if Spotify is enabled

subsonicenablemaintenancefeatures = bool

Enables maintenance features, e.g. list albums without MusicBrainz Id Set it to 1 in order to enable library maintenance features, disabled by default

subsonicartistalbumnewestfirst = bool

Show artist albums from newest to older if left empty or set to 1 Allows to change sort order to artist albums. Set it to 0 if you want the order to be ascending instead of descending (default)

subsonicmaxrandomsonglistsize = int

Number of songs in Random Songs (list) Set the maximum number of songs in Random Songs (list), defaults to 250, cannot be more than 500

bbcuser = string

Bogus user name variable. Set this to activate the plugin, the value is ignored.

bbcprogrammedays = string

Past days in BBC Sounds catalog listing. This controls how many days are listed in the station displays.

bbctitle = string

Plugin Title. This will be displayed as the plugin entry in the Media Server root directory.

sclogfilename = fn

Log file name for sc2mpd (default stderr) The value *must not* be the same as the one used for upmpdcli (except if empty).

scloglevel = int

Log verbosity for sc2mpd.

scplaymethod = cstr

sc2mpd play method (mpd/alsa). With this set as 'alsa', sc2mpd will send the audio directly to the sound driver, which is the only way to really avoid skips and control the synchronization in multi-room setups. *For 'alsa', make sure that user upmpdcli has permission to access the audio devices !*

schttpport = int

Port used by sc2mpd for MPD to connect to. Used only for scplaymethod=mpd. sc2mpd only accepts connections from localhost.

scalsadevice = string

Alsa device used by sc2mpd for playing audio. Only used for scplaymethod=alsa. Use 'aplay -L' to see the possible values.

sccvttype = cstr

sc2mpd resampling method. Only used for scplaymethod=alsa. sc2mpd uses libsamplerate. The default method is SRC_SINC_FASTEST and a Rasberry Pi 1 is fast enough to use it. Possible values: SRC_SINC_BEST_QUALITY, SRC_SINC_MEDIUM_QUALITY, SRC_SINC_FASTEST, SRC_ZERO_ORDER_HOLD, SRC_LINEAR. See the libsamplerate documentation for descriptions. Anything above SRC_SINC_FASTEST needs a serious CPU. BEST_QUALITY uses approx 25% cpu on a core i7 4770T. Obviously too much, actually might not be sustainable (it's almost 100% of 1 cpu). MEDIUM_QUALITY is around 10% on the same machine, FASTEST is 4-5%. Given that this is measured for the full process, probably a couple % for the conversion in fact. NONE will turn resampling off: minimum CPU and best quality, but guaranteed glitches from time to time, depending on the clocks skew.

scusempdvolume = bool

Scale songcast stream based on mpd volume value Allow controlling the volume from the Control Point by scaling the stream according to the mpd volume value. Only works when scplaymethod is 'alsa'.

sc2mpd = string

Path to sc2mpd. Only useful if it is not in /usr/bin and the location is not in the $PATH for the init scripts.

screceiverstatefile = string

Path to a screceiver state file. If set, the sender uri and metadata will be read from the file when initializing the Songcast Receiver service and written to the file when a Sender is set for the service. Useful for preserving the sender information between restarts.

scstreamcodec = string

!!Standard Songcast receivers only support PCM!! Codec to use for the network stream. Set to empty or PCM to support foreign receivers. Or use FLAC or OPUS for lower network load.

scsenderpath = fn

Path to starter script This is normally scmakempdsender which starts the auxiliary mpd and the sender process. Empty and searched in the PATH by default.

scstreamscaled = bool

Scale the Songcast stream. If set, MPD software volume control will be applied to the stream. True by default: using a Control Point to set the volume on the upmpdcli instance which started the Sender affects the volume for all Receivers.

scsendermpdport = int

localhost port to be used by the auxiliary mpd.

scripts_dir = dfn

External sources script directory. Location for the scripts used to set up additional external sources. See the Songcast Sender support documentation page.

scscriptgracesecs = int

Grace period to wait for a script process to exit before it is forcely killed. In seconds. Default 2 S.

## SEE ALSO
upmpdcli(1)


usbguard-daemon.conf

package: usbguard

title: usbguard-daemon.conf(5)

summary: USBGuard daemon configuration file

text:
# usbguard-daemon.conf(5)

## NAME
usbguard-daemon.conf - USBGuard daemon configuration file

## DESCRIPTION
The usbguard-daemon.conf file is loaded by the USBGuard daemon after it parses its command-line options. It is used to configure runtime parameters of the daemon. The default search path is /etc/usbguard/usbguard-daemon.conf. It may be overridden using the -c command-line option, see usbguard-daemon(8) for further details.

## OPTIONS
RuleFile=path

The USBGuard daemon will use this file to load the policy rule set from it and to write new rules received via the IPC interface. Default: %sysconfdir%/usbguard/rules.conf

RuleFolder=path

The USBGuard daemon will use this folder to load the policy rule set from it and to write new rules received via the IPC interface. Usually, we set the option to /etc/usbguard/rules.d/. The USBGuard daemon is supposed to behave like any other standard Linux daemon therefore it loads rule files in alpha-numeric order. File names inside RuleFolder directory should start with a two-digit number prefix indicating the position, in which the rules are scanned by the daemon. Using RuleFile and RuleFolder at the same time is permitted. However, modification of the permanent policy is not possible if one of the following conditions are met:

•Neither RuleFile nor RuleFolder are specified.

•RuleFile is not specified, RuleFolder is but it does not contain any files, where we could save permanent rules.

ImplicitPolicyTarget=target

How to treat USB devices that don’t match any rule in the policy. Target should be one of allow, block or reject (logically remove the device node from the system). Default: block

PresentDevicePolicy=policy

How to treat USB devices that are already connected when the daemon starts. Policy should be one of allow, block, reject, keep (keep whatever state the device is currently in) or apply-policy (evaluate the rule set for every present device). Default: apply-policy

PresentControllerPolicy=policy

How to treat USB controller devices that are already connected when the daemon starts. One of allow, block, reject, keep or apply-policy. Default: keep

InsertedDevicePolicy=policy

How to treat USB devices that are already connected after the daemon starts. One of block, reject, apply-policy. Default: apply-policy

AuthorizedDefault=authorizedDefault

The USBGuard daemon modifies some of the default authorization state attributes of controller devices. This setting, enables you to define what value the default authorization is set to. Authorized default should be one of keep (do not change authorization state), none (every new device starts out deauthorized), all (every new device starts out authorized) or internal (internal devices start out authorized, external do not). Default: none

RestoreControllerDeviceState=boolean

The USBGuard daemon modifies some attributes of controller devices like the default authorization state of new child device instances. Using this setting, you can control whether the daemon will try to restore the attribute values to the state before modification on shutdown. Default: false

DeviceManagerBackend=backend

Which device manager backend implementation to use. Backend should be one of uevent (default) or umockdev (useful for testing). UEvent backend is a netlink based implementation which uses sysfs to scan for present devices and an uevent socket for receiving USB device related events. UMockDev based device manager is capable of simulating devices based on umockdev-record files. Default: uevent

IPCAllowedUsers=username [username ...]

A space delimited list of usernames that the daemon will accept IPC connections from. Default: root

IPCAllowedGroups=groupname [groupname ...]

A space delimited list of groupnames that the daemon will accept IPC connections from.

IPCAccessControlFiles=path

The files at this location will be interpreted by the daemon as IPC access control definition files. See the IPC ACCESS CONTROL section for more details.

DeviceRulesWithPort=boolean

Generate device specific rules including the "via-port" attribute. Default: false

AuditBackend=backend

USBGuard audit events log backend. The backend value should be one of FileAudit or LinuxAudit. Default: FileAudit

AuditFilePath=filepath

USBGuard audit events log file path. Required if AuditBackend is set to FileAudit. Default: %localstatedir%/log/usbguard/usbguard-audit.log

HidePII=boolean

Hides personally identifiable information such as device serial numbers and hashes of descriptors (which include the serial number) from audit entries. Default: false

## SECURITY CONSIDERATIONS

### IPC
The daemon provides the USBGuard public IPC interface. Depending on your distribution defaults, access to this interface is limited to a certain group or a specific user only. Please set either the IPCAllowedUsers, IPCAllowedGroups or IPCAccessControlFiles options to limit access to the IPC interface. Do not leave the ACL unconfigured as that will expose the IPC interface to all local users and will allow them to manipulate the authorization state of USB devices and modify the USBGuard policy.

### RestoreControllerDeviceState configuration option
If set to true, the USB authorization policy could be bypassed by performing some sort of attack on the daemon (via a local exploit or via a USB device) to make it shutdown and restore to the operating-system default state (known to be permissive).

## IPC ACCESS CONTROL
Access to the USBGuard IPC interface can be limited per user or group. Furthermore, by using the IPC Access Control files, it is possible to limit the access down to the level of Sections and Privileges as explained below.

### Recommended: IPCAccessControlFiles
When you set IPCAccessControlFiles option, the daemon will look for IPC access control files in the directory specified by the set value. Each file in the directory is processed as follows:

1.The basename of the file is interpreted as a username, UID, groupname or GID. If the name starts with : (colon), it is assumed that the rest of the name represents a group identifier (groupname or GID in case of a numeric-only string). Otherwise, it is interpreted as a user identifier (username or UID in case of numeric-only string).

2.The contents of the file are parsed as Section=[privilege1][,privilege2] ... formatted lines which specify the section privileges. If a section is omitted, it is assumed that no privileges are given for that section.

Available sections and privileges:

•Devices

•modify: Change authorization state of devices including permanent changes (i.e. modification of device specific rules in the policy).

•list: Ability to get a list of recognized devices and their attributes.

•listen: Listen to device presence and device policy changes.

•Policy

•modify: Append rules to or remove any rules from the policy.

•list: Ability to view the currently enforced policy.

•Exceptions

•listen: Receive exception messages.

•Parameters

•modify: Set values of run-time parameters.

•list: Get values of run-time parameters.

•listen: Listen to property parameter changes.

The following is a generally usable and reasonably safe example of an access control file. It allows one to modify USB device authorization state (Devices=modify), list USB devices (Devices=list), listen to USB device related events (Devices=listen), list USB authorization policy rules (Policy=list) and listen to exception events (Exceptions=listen):

```
Devices=modify,list,listen
Policy=list
Exceptions=listen
```

You can create or remove the IPC access control files using usbguard add-user and usbguard remove-user CLI commands. See usbguard(1) for more details. If you want to create the IPC access control files manually, you need to set the files permissions to 0600.

### Legacy: IPCAllowedUsers and IPCAllowedGroups
Example configuration allowing full IPC access to users root, joe and members of the group wheel:

```
IPCAllowedUsers=root joe
IPCAllowedGroups=wheel
```

## SEE ALSO
usbguard-daemon(8), usbguard-rules.conf(5)

## BUGS
If you find a bug in this software or if you’d like to request a feature to be implemented, please file a ticket at https://github.com/USBGuard/usbguard/issues/new.

## AUTHOR
USBGuard was originally written by Daniel Kopeček. Many people have contributed to it.

## RESOURCES
Main web site: https://usbguard.github.io/

## COPYING
License GPLv2+: GNU GPL version 2 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


usbguard-rules.conf

title: usbguard-rules.conf(5)

summary: USBGuard rule set file.

text:
# usbguard-rules.conf(5)

## NAME
usbguard-rules.conf - USBGuard rule set file.

## DESCRIPTION
The usbguard-rules.conf file is loaded by the USBGuard daemon after it parses the main configuration file, usbguard-daemon.conf(5). The daemon expects the file to contain rules written in a language which is described in the Rule Language section below.

## RULE LANGUAGE
The USBGuard daemon decides which USB device to authorize based on a policy defined by a set of rules. When a USB device is inserted into the system, the daemon scans the existing rules sequentially. If a matching rule is found, it either authorizes (allows), deauthorizes (blocks) or removes (rejects) the device, based on the rule target. If no matching rule is found, the decision is based on an implicit default target. This implicit default is to block the device until a decision is made by the user. The rule language grammar, expressed in a BNF-like syntax, is the following:

```
    rule ::= target attributes.

    target ::= "allow" | "block" | "reject".

    attributes ::= attributes | attribute.

    attributes ::= .
```

Rule attributes specify which devices to match or what condition have to be met for the rule to be applicable. See the Device Specification section for the list of available attributes and Conditions for the list of supported rule rule conditions.

### Targets
The target of a rule specifies whether the device will be authorized for use or not. Three types of target are recognized:

•allow - Authorize the device. The device and its interfaces will be allowed to communicate with the system.

•block - Deauthorize the device. The device will remain in a blocked state until it is authorized.

•reject - Deauthorize and Remove the device from the system. The device will have to be re-inserted to become visible to the system again.

### Device Specification
Except the target, all the other fields of a rule are optional. A rule where only the target is specified will match any device. That allows the policy administrator to write an explicit default target. If no rule from the policy is applicable to the device, an implicit target configured in usbguard-daemon.conf(5) will be used. However, if one wants to narrow the applicability of a rule to a set of devices or one device only, it’s possible to do so with device attributes and rule conditions.

Device Attributes

Device attributes are specific values read from the USB device after it’s inserted to the system. Which attributes are available is defined below. Some of the attributes are derived and some are based on attributes read directly from the device. All attributes support two forms:

•single-valued with a syntax:

```
    name value
```

•multi-valued with a syntax:

```
    name [operator] { value1 value2 ... }
```

where the optional operator is one of:

all-of

The device attribute set must contain all of the specified values for the rule to match.

one-of

The device attribute set must contain at least one of the specified values for the rule to match.

none-of

The device attribute set must not contain any of the specified values for the rule to match.

equals

The device attribute set must contain exactly the same set of values for the rule to match.

equals-ordered

The device attribute set must contain exactly the same set of values in the same order for the rule to match.

match-all

The device attribute set must be a subset of the specified values for the rule to match.

If the operator is not specified it is set to equals.

List of attributes:

id usb-device-id

Match a USB device ID.

id [operator] { usb-device-id ... }

Match a set of USB device IDs.

hash "value"

Match a hash computed from the device attribute values and the USB descriptor data. The hash is computed for every device by USBGuard.

hash [operator] { "value" ... }

Match a set of device hashes.

parent-hash "value"

Match a hash of the parent device.

parent-hash [operator] { "value" ... }

Match a set of parent device hashes.

name "device-name"

Match the USB device name attribute.

name [operator] { "device-name" ... }

Match a set of USB device names.

serial "serial-number"

Match the USB iSerial device attribute.

serial [operator] { "serial-number" ... }

Match a set of USB iSerial device attributes.

via-port "port-id"

Match the USB port through which the device is connected. Note that some systems have unstable port numbering. The port might change after the system reboots or when certain kernel modules are reloaded. Use the parent-hash attribute if you want to ensure that a device is connected via a specific parent device.

via-port [operator] { "port-id" ... }

Match a set of USB ports.

with-interface interface-type

Match an interface type that the USB device provides.

with-interface [operator] { interface-type ... }

Match a set of interface types against the set of interfaces that the USB device provides.

with-connect-type "connect-type"

Match the USB port/connect_type device attribute.

with-connect-type [operator] { "connect-type" ... }

Match a set of USB port/connect_type device attributes.

label "label"

Associates arbitrary string with a rule. Label is useful for storing some contextual information about rule or for filtering rules by label. This attribute is not used when testing if a rule applies to a device.

The usb-device-id is a colon delimited pair in the form vendor_id:product_id. All USB devices have this ID assigned by the manufacturer and it should uniquely identify a USB product type. Both vendor_id and product_id are 16-bit numbers represented in hexadecimal base. It’s possible to use an asterisk character to match either any device ID *:* or any product ID from a specific vendor, e.g. 1234:*.

The port-id value is a platform specific USB port identification. On Linux it’s in the form of "usbN" in case of a USB controller (more accurately a "root hub") or "bus-port[.port[.port ...]]" (e.g. 1-2, 1-2.1, ...) in case of a USB device.

The interface-type represents a USB interface and should be formatted as three 8-bit numbers in hexadecimal base delimited by a colon character, i.e. cc:ss:pp. The numbers represent the interface class (cc), subclass (ss) and protocol (pp) as assigned by the USB-IF. See the list of assigned classes, subclasses and protocols for details. Instead of the subclass and protocol number, you may write an asterisk character (*) to match all subclasses or protocols. Matching a specific class and a specific protocol is not allowed, i.e. if you use an asterisk as the subclass number, you have to use an asterisk for the protocol too.

### Conditions
Whether a rule that matches a device will be applied or not can be further restricted using rule conditions. If the condition expression is met at the rule evaluation time, then the rule target is applied for the device. A condition expression is met if it evaluates to true. Otherwise, the rule evaluation continues with the next rule. A rule conditions has the following syntax:

```
     if [!]condition

     if [operator] { [!]conditionA [!]conditionB ... }
```

Optionally, an exclamation mark (!) can be used to negate the result of a condition.

Interpretation of the set operator:

all-of

Evaluate to true if all of the specified conditions evaluated to true.

one-of

Evaluate to true if one of the specified conditions evaluated to true.

none-of

Evaluate to true if none of the specified conditions evaluated to true.

equals

Same as all-of.

equals-ordered

Same as all-of.

List of conditions:

localtime(time_range)

Evaluates to true if the local time is in the specified time range. time_range can be written either as HH:MM[:SS] or HH:MM[:SS]-HH:MM[:SS].

allowed-matches(query)

Evaluates to true if an allowed device matches the specified query. The query uses the rule syntax. Conditions in the query are not evaluated.

rule-applied

Evaluates to true if the rule currently being evaluated ever matched a device.

rule-applied(past_duration)

Evaluates to true if the rule currently being evaluated matched a device in the past duration of time specified by the parameter. past_duration can be written as HH:MM:SS, HH:MM, or SS.

rule-evaluated

Evaluates to true if the rule currently being evaluated was ever evaluated before.

rule-evaluated(past_duration)

Evaluates to true if the rule currently being evaluated was evaluated in the pas duration of time specified by the parameter. past_duration can be written as HH:MM:SS, HH:MM, or SS.

random

Evaluates to true/false with a probability of p(true)=0.5.

random(p_true)

Evaluates to true with the specified probability p(true)=p_true.

true

Evaluates always to true.

false

Evaluates always to false.

### Partial rule
Partial rule is a rule without a rule target. Partial rules may by used by some commands of usbguard CLI tool.

### Comments
In order to easily understand the meaning of each rule, comments can be used. Everything after the "#" character is ignored by the rule parser.

## INITIAL POLICY
Using the usbguard CLI tool and its generate-policy subcommand, you can generate an initial policy for your system instead of writing one from scratch. The tool generates an allow policy for all devices connected to the system at the time of execution. It has several options to tweak the resulting policy, see usbguard(1) for further details.

The policy will be printed out on the standard output. It’s a good idea to review the generated rules before using them on a system. The typical workflow for generating an initial policy could look like this:

```
    $ sudo usbguard generate-policy > rules.conf

    $ vi rules.conf

    (review/modify the rule set)

    $ sudo install -m 0600 -o root -g root rules.conf /etc/usbguard/rules.conf

    $ sudo systemctl restart usbguard
```

## EXAMPLE POLICIES
The following examples show what to put into the rules.conf file in order to implement the given policy.

1.Allow USB mass storage devices (USB flash disks) and block everything else This policy will block any device that isn’t just a mass storage device. Devices with a hidden keyboard interface in a USB flash disk will be blocked. Only devices with a single mass storage interface will be allowed to interact with the operating system. The policy consists of a single rule:

```
    allow with-interface equals { 08:*:* }
```

The blocking is implicit in this case because we didn’t write a block rule. Implicit blocking is useful to desktop users. A desktop applet listening to USBGuard events can ask the user for a decision if an implicit target was applied.

2.Allow a specific Yubikey device to be connected via a specific port (and reject everything else on that port)

```
    allow 1050:0011 name "Yubico Yubikey II" serial "0001234567" via-port "1-2" hash "044b5e168d40ee0245478416caf3d998"

    reject via-port "1-2"
```

We could use just the hash to match the device. However, using the name and serial attributes provide an useful hint for later inspection of the policy. On the other hand, the hash is the most specific value we can use to identify a device. It’s the best attribute to use if you want a rule to match just one device.

3.Reject devices with suspicious combination of interfaces A USB flash disk which implements a keyboard or a network interface is very suspicious. The following set of rules forms a policy that allows USB flash disks and explicitly rejects devices with an additional and suspicious (as defined before) interface.

```
    allow with-interface equals { 08:*:* }

    reject with-interface all-of { 08:*:* 03:00:* }

    reject with-interface all-of { 08:*:* 03:01:* }

    reject with-interface all-of { 08:*:* e0:*:* }

    reject with-interface all-of { 08:*:* 02:*:* }
```

The policy rejects all USB flash disk devices with an interface from the HID/Keyboard, Communications and Wireless classes. Note that default allow is the wrong approach and you shouldn’t just reject a set of devices and allow the rest. The policy above assumes that blocking is the default. Rejecting a set of devices considered as "bad" is a good approach how to limit the exposure of the OS to such devices as much as possible.

4.Allow a keyboard-only USB device only if there isn’t already a USB device with a keyboard interface allowed

```
    allow with-interface one-of { 03:00:01 03:01:01 } if !allowed-matches(with-interface one-of { 03:00:01 03:01:01 })
```

5.Play "Russian roulette" with USB devices

```
    allow if random(0.1666)

    reject
```

## SEE ALSO
usbguard-daemon(8), usbguard-daemon.conf(5)

## BUGS
If you find a bug in this software or if you’d like to request a feature to be implemented, please file a ticket at https://github.com/USBGuard/usbguard/issues/new.

## AUTHOR
USBGuard was originally written by Daniel Kopeček. Many people have contributed to it.

## RESOURCES
Main web site: https://usbguard.github.io/

## COPYING
License GPLv2+: GNU GPL version 2 or later http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.


terminal-colors.d

package: util-linux

title: terminal-colors.d(5)

text:
# terminal-colors.d(5)

## NAME
terminal-colors.d - configure output colorization for various utilities

## SYNOPSIS
/etc/terminal-colors.d/[[name][@term].][type]

## DESCRIPTION
Files in this directory determine the default behavior for utilities when coloring output.

The name is a utility name. The name is optional and when none is specified then the file is used for all unspecified utilities.

The term is a terminal identifier (the TERM environment variable). The terminal identifier is optional and when none is specified then the file is used for all unspecified terminals.

The type is a file type. Supported file types are:

disable

Turns off output colorization for all compatible utilities.

enable

Turns on output colorization; any matching disable files are ignored.

scheme

Specifies colors used for output. The file format may be specific to the utility, the default format is described below.

If there are more files that match for a utility, then the file with the more specific filename wins. For example, the filename "@xterm.scheme" has less priority than "dmesg@xterm.scheme". The lowest priority are those files without a utility name and terminal identifier (e.g., "disable").

The user-specific $XDG_CONFIG_HOME/terminal-colors.d or $HOME/.config/terminal-colors.d overrides the global setting.

## DEFAULT SCHEME FILES FORMAT
The following statement is recognized:

name color-sequence

The name is a logical name of color sequence (for example "error"). The names are specific to the utilities. For more details always see the COLORS section in the man page for the utility.

The color-sequence is a color name, ASCII color sequences or escape sequences.

### Color names
black, blink, blue, bold, brown, cyan, darkgray, gray, green, halfbright, lightblue, lightcyan, lightgray, lightgreen, lightmagenta, lightred, magenta, red, reset, reverse, and yellow.

### ANSI color sequences
The color sequences are composed of sequences of numbers separated by semicolons. The most common codes are:

0

to restore default color

1

for brighter colors

4

for underlined text

5

for flashing text

30

for black foreground

31

for red foreground

32

for green foreground

33

for yellow (or brown) foreground

34

for blue foreground

35

for purple foreground

36

for cyan foreground

37

for white (or gray) foreground

40

for black background

41

for red background

42

for green background

43

for yellow (or brown) background

44

for blue background

45

for purple background

46

for cyan background

47

for white (or gray) background

### Escape sequences
To specify control or blank characters in the color sequences, C-style \-escaped notation can be used:

\a

Bell (ASCII 7)

\b

Backspace (ASCII 8)

\e

Escape (ASCII 27)

\f

Form feed (ASCII 12)

\n

Newline (ASCII 10)

\r

Carriage Return (ASCII 13)

\t

Tab (ASCII 9)

\v

Vertical Tab (ASCII 11)

\?

Delete (ASCII 127)

\_

Space

\\

Backslash (\)

\^

Caret (^)

\#

Hash mark (#)

Please note that escapes are necessary to enter a space, backslash, caret, or any control character anywhere in the string, as well as a hash mark as the first character.

For example, to use a red background for alert messages in the output of dmesg(1), use:

echo 'alert 37;41' >> /etc/terminal-colors.d/dmesg.scheme

### Comments
Lines where the first non-blank character is a # (hash) are ignored. Any other use of the hash character is not interpreted as introducing a comment.

## ENVIRONMENT
TERMINAL_COLORS_DEBUG=all

enables debug output.

## FILES
$XDG_CONFIG_HOME/terminal-colors.d

$HOME/.config/terminal-colors.d

/etc/terminal-colors.d

## EXAMPLE
Disable colors for all compatible utilities:

touch /etc/terminal-colors.d/disable

Disable colors for all compatible utils on a vt100 terminal:

touch /etc/terminal-colors.d/@vt100.disable

Disable colors for all compatible utils except dmesg(1):

touch /etc/terminal-colors.d/disable

touch /etc/terminal-colors.d/dmesg.enable

## COMPATIBILITY
The terminal-colors.d functionality is currently supported by all util-linux utilities which provides colorized output. For more details always see the COLORS section in the man page for the utility.

## REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.

## AVAILABILITY
terminal-colors.d is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.


utoprc

package: utop

title: utoprc(5)

summary: Configuration file of utop

text:
# utoprc(5)

## NAME
utoprc - Configuration file of utop

## SYNOPSIS
~/.utoprc

## DESCRIPTION
This manual page describes the format of the ~/.utoprc file. This is a text file which contains the configuration of utop. Comments start with a '!' and empty lines are ignored. Configuration lines are of the form:

<wildcard>: <value>

<wildcard> may contain the '*' asterisk character. In that case any key which matches the pattern is given the value after the colon.

The boolean key autoload can be set to false to disable the autoloading of files in $OCAML_TOPLEVEL_PATH/autoload at startup.

The key external-editor can be set to a command line. It is used to edit the input when pressing C-x C-e. It defaults to the contents of the EDITOR environment variable.

The key profile may have the value dark or light. This is the same as calling UTop.set_profile in ~/.config/utop/init.ml.

The following style keys are used by utop:

* identifier

* module

* comment

* doc

* constant

* keyword

* symbol

* string

* char

* quotation

* error

* directive

* parenthesis

* blanks

For each of these keys, the following sub-keys are used:

* key.foreground

* key.background

* key.bold

* key.underline

* key.reverse

* key.blink

key.foreground and key.background are colors, and the others are booleans. Colors may be one of the standard terminal colors:

* black

* red

* green

* yellow

* blue

* magenta

* cyan

* white

* light-black

* light-red

* light-green

* light-yellow

* light-blue

* light-magenta

* light-cyan

* light-white

or X11 colors, prefixed with "x-". For example:

identifier.foreground: x-goldenrod

Colors can also be given by their RGB components, written #RRGGBB. For example:

identifier.foreground: #5fbf7f

utop will choose the nearest color of the terminal when specifying an X11 color or a color given by its RGB components. If you are using gnome-terminal or konsole, you can enable 256 colors by setting the environment variable TERM to "xterm-256color".

## FILES
~/.utoprc

## EXAMPLE
profile: dark

identifier.foreground: none

comment.foreground: x-chocolate1

doc.foreground: x-light-salmon

constant.foreground: x-aquamarine

keyword.foreground: x-cyan1

symbol.foreground: x-cyan1

string.foreground: x-light-salmon

char.foreground: x-light-salmon

quotation.foreground: x-purple

error.foreground: x-red

parenthesis.background: blue

## AUTHOR
Jérémie Dimino <jeremie@dimino.org>

## SEE ALSO
utop(1).


crontab

package: vixie-cron

title: crontab(5)

summary: tables for driving cron

text:
# crontab(5)

## NAME
crontab — tables for driving cron

## DESCRIPTION
A crontab file contains instructions to the cron(8) daemon of the general form: “at these times on these dates run this command”. There may be a system crontab (/etc/crontab) and each user may have their own crontab (/var/spool/cron/<user>). Commands in any given crontab will be executed either as the user who owns the crontab or, in the case of the system crontab, as the user specified in the command line. Uucp and News will usually each have their own crontab, eliminating the need for explicitly running su(1) as part of a cron(8) command.

While a crontab is a text file, it is not intended to be directly edited. Creation, modification, and removal of a crontab should be done using crontab(1).

Blank lines, leading spaces, and tabs are ignored. Lines whose first non-space character is a pound sign (‘#’) are comments, and are ignored. Note that comments are not allowed on the same line as cron(8) commands, since they will be taken to be part of the command. Similarly, comments are not allowed on the same line as environment variable settings.

An active line in a crontab is either an environment variable setting or a cron(8) command.

Environment Variable Settings

Environment variable settings create the environment any command in the crontab is run in. An environment variable setting is of the form:

name = value

where the spaces around the equal-sign (‘=’) are optional, and any subsequent non-leading spaces in value will be part of the value assigned to name. The value string may be placed in quotes (single or double, but matching) to preserve leading or trailing blanks.

Several environment variables are set automatically by the cron(8) daemon. SHELL is set to /bin/sh, and LOGNAME and HOME are set from the /etc/passwd line of the crontab's owner. HOME and SHELL may be overridden by settings in the crontab; LOGNAME may not.

Note: on BSD systems the LOGNAME variable is sometimes called USER. On OpenBSD, cron(8) will set both USER and LOGNAME to the same value.

In addition to LOGNAME, HOME, and SHELL, cron(8) will look at MAILTO if it has any reason to send mail as a result of running commands in “this” crontab. If MAILTO is defined (and non-empty), mail is sent to the user so named. If MAILTO is defined but empty (MAILTO = ‘’), no mail will be sent. Otherwise mail is sent to the owner of the crontab. This option is useful for pseudo-users that lack an alias that would otherwise redirect the mail to a real person.

The MLS_LEVEL environment variable provides support for multiple per-job SELinux security contexts in the same crontab. By default, cron jobs execute with the default SELinux security context of the user that created the crontab file. When using multiple security levels and roles, this may not be sufficient, because the same user may be running in a different role or at a different security level. For more about roles and SELinux MLS/MCS see selinux(8) and undermentioned crontab example. You can set MLS_LEVEL to the SELinux security context string specifying the SELinux security context in which you want the job to run, and crond will set the execution context of the or jobs to which the setting applies to the specified context. See also the crontab(1) -s option.

cron Commands

The format of a cron(8) command is very much the V7 standard, with a number of upward-compatible extensions. Lines in the system crontab have six fixed fields plus a command in the form:

minute hour day-of-month month day-of-week user command

While lines in a user crontab have five fixed fields plus a command in the form:

minute hour day-of-month month day-of-week command

Fields are separated by blanks or tabs. The command may be one or more fields long. The allowed values for the fields are:

field

allowed values

-----

--------------

minute

* or 0-59

hour

* or 0-23

day-of-month

* or 1-31

month

* or 1-12 or a name (see below)

day-of-week

* or 0-7 or a name (0 or 7 is Sunday)

user

a valid username

command

text

Lists are allowed. A list is a set of numbers (or ranges) separated by commas. Examples: “1,2,5,9”,“0-4,8-12”.

Ranges of numbers are allowed. Ranges are two numbers separated with a hyphen. The specified range is inclusive. For example, 8-11 for an hour entry specifies execution at hours 8, 9, 10 and 11.

Step values can be used in conjunction with ranges. Following a range with /number specifies skips of number through the range. For example, “0-23/2” can be used in the hour field to specify command execution every other hour (the alternative in the V7 standard is “0,2,4,6,8,10,12,14,16,18,20,22”). Steps are also permitted after an asterisk, so if you want to say “every two hours”, just use “*/2”.

An asterisk (‘*’) is short form for a range of all allowed values.

Names can be used in the month and day-of-week fields. Use the first three letters of the particular day or month (case doesn't matter). Ranges or lists of names are not allowed.

The command field (the rest of the line) is the command to be run. The entire command portion of the line, up to a newline or % character, will be executed by /bin/sh or by the shell specified in the SHELL variable of the crontab. Percent signs (‘%’) in the command, unless escaped with a backslash (‘\’), will be changed into newline characters, and all data after the first ‘%’ will be sent to the command as standard input.

Commands are executed by cron(8) when the minute, hour, and month fields match the current time, and when at least one of the two day fields (day-of-month or day-of-week, see Note below) match the current time. cron(8) examines crontab entries once every minute.

Note: The day of a command's execution can be specified by two fields — day-of-month and day-of-week. If both fields are restricted (i.e., aren't *), the command will be run when either field matches the current time. For example,

30 4 1,15 * 5

would cause a command to be run at 4:30 am on the 1st and 15th of each month, plus every Friday.

Instead of the first five fields, one of eight special strings may appear:

string

meaning

------

-------

@reboot

Run once, at cron(8) startup.

@yearly

Run every January 1, "0 0 1 1 *".

@annually

(same as @yearly).

@monthly

Run the first day of every month, "0 0 1 * *".

@weekly

Run every Sunday, "0 0 * * 0".

@daily

Run every midnight, "0 0 * * *".

@midnight

(same as @daily).

@hourly

Run every hour, on the hour, "0 * * * *".

## EXAMPLES

```
# use /bin/sh to run commands, no matter what /etc/passwd says
SHELL=/bin/sh
# mail any output to `paul', no matter whose crontab this is
MAILTO=paul
#
# run five minutes after midnight, every day
5 0 * * *       $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
# run at 2:15pm on the first of every month -- output mailed to paul
15 14 1 * *     $HOME/bin/monthly
# run at 10 pm on weekdays, annoy Joe
0 22 * * 1-5	mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
5 4 * * sun     echo "run at 5 after 4 every sunday"
```

## SELinux with multi level security (MLS)
In crontab is important specified security level by crontab -s or specifying the required level on the first line of the crontab. Each level is specified in /etc/selinux/targeted/seusers. For using crontab in MLS mode is really important:

- check/change actual role,

- set correct role for directory, which is used for input/output.

## EXAMPLE FOR SELINUX MLS

```
# login as root
newrole -r sysadm_r
mkdir /tmp/SystemHigh
chcon -l SystemHigh /tmp/SystemHigh
crontab -e
# write in crontab file
MLS_LEVEL=SystemHigh
0-59 * * * * id -Z > /tmp/SystemHigh/crontest
When I log in as a normal user, it can't work, because /tmp/SystemHigh is
higher than my level.
```

## SEE ALSO
crontab(1), cron(8)

## EXTENSIONS
When specifying day-of-week, both day 0 and day 7 will be considered Sunday. BSD and ATT seem to disagree about this.

Lists and ranges are allowed to coexist in the same field. “1-3,7-9” would be rejected by ATT or BSD cron — they want to see “1-3” or “7,8,9” only.

Ranges can include “steps”, so “1-9/2” is the same as “1,3,5,7,9”.

Months or days of the week can be specified by name.

Environment variables can be set in the crontab. In BSD or ATT, the environment handed to child processes is basically the one from /etc/rc.

Command output is mailed to the crontab owner (BSD can't do this), can be mailed to a person other than the crontab owner (SysV can't do this), or the feature can be turned off and no mail will be sent at all (SysV can't do this either).

All of the ‘@’ commands that can appear in place of the first five fields are extensions.

## AUTHORS
Paul Vixie ⟨vixie@isc.org⟩