mosquitto.conf

package: mosquitto

title: mosquitto.conf(5)

summary: the configuration file for mosquitto

text:
# mosquitto.conf(5)

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

## SYNOPSIS
mosquitto.conf

## DESCRIPTION
mosquitto.conf is the configuration file for mosquitto. This file can reside anywhere as long as mosquitto can read it. By default, mosquitto does not need a configuration file and will use the default values listed below. See mosquitto(8) for information on how to load a configuration file.

Mosquitto can be instructed to reload the configuration file by sending a SIGHUP signal as described in the Signals section of mosquitto(8). Not all configuration options can be reloaded, as detailed in the options below.

## FILE FORMAT
All lines with a # as the very first character are treated as a comment.

Configuration lines start with a variable name. The variable value is separated from the name by a single space.

## AUTHENTICATION
The authentication options described below allow a wide range of possibilities in conjunction with the listener options. This section aims to clarify the possibilities. An overview is also available at https://mosquitto.org/documentation/authentication-methods/

The simplest option is to have no authentication at all. This is the default if no other options are given. Unauthenticated encrypted support is provided by using the certificate based SSL/TLS based options certfile and keyfile.

MQTT provides username/password authentication as part of the protocol. Use the password_file option to define the valid usernames and passwords. Be sure to use network encryption if you are using this option otherwise the username and password will be vulnerable to interception. Use the per_listener_settings to control whether passwords are required globally or on a per-listener basis.

Mosquitto provides the Dynamic Security plugin which handles username/password authentication and access control in a much more flexible way than a password file. See https://mosquitto.org/documentation/dynamic-security/

When using certificate based encryption there are three options that affect authentication. The first is require_certificate, which may be set to true or false. If false, the SSL/TLS component of the client will verify the server but there is no requirement for the client to provide anything for the server: authentication is limited to the MQTT built in username/password. If require_certificate is true, the client must provide a valid certificate in order to connect successfully. In this case, the second and third options, use_identity_as_username and use_subject_as_username, become relevant. If set to true, use_identity_as_username causes the Common Name (CN) from the client certificate to be used instead of the MQTT username for access control purposes. The password is not used because it is assumed that only authenticated clients have valid certificates. This means that any CA certificates you include in cafile or capath will be able to issue client certificates that are valid for connecting to your broker. If use_identity_as_username is false, the client must authenticate as normal (if required by password_file) through the MQTT options. The same principle applies for the use_subject_as_username option, but the entire certificate subject is used as the username instead of just the CN.

When using pre-shared-key based encryption through the psk_hint and psk_file options, the client must provide a valid identity and key in order to connect to the broker before any MQTT communication takes place. If use_identity_as_username is true, the PSK identity is used instead of the MQTT username for access control purposes. If use_identity_as_username is false, the client may still authenticate using the MQTT username/password if using the password_file option.

Both certificate and PSK based encryption are configured on a per-listener basis.

Authentication plugins can be created to augment the password_file, acl_file and psk_file options with e.g. SQL based lookups.

It is possible to support multiple authentication schemes at once. A config could be created that had a listener for all of the different encryption options described above and hence a large number of ways of authenticating.

## GENERAL OPTIONS
acl_file file path

Set the path to an access control list file. If defined, the contents of the file are used to control client access to topics on the broker. If this parameter is defined then only the topics listed will have access. Topic access is added with lines of the format:

topic [read|write|readwrite|deny] <topic>

The access type is controlled using "read", "write", "readwrite" or "deny". This parameter is optional (unless <topic> includes a space character) - if not given then the access is read/write. <topic> can contain the + or # wildcards as in subscriptions. The "deny" option can used to explicitly deny access to a topic that would otherwise be granted by a broader read/write/readwrite statement. Any "deny" topics are handled before topics that grant read/write access.

The first set of topics are applied to anonymous clients, assuming allow_anonymous is true. User specific topic ACLs are added after a user line as follows:

user <username>

The username referred to here is the same as in password_file. It is not the clientid.

It is also possible to define ACLs based on pattern substitution within the topic. The form is the same as for the topic keyword, but using pattern as the keyword.

pattern [read|write|readwrite|deny] <topic>

The patterns available for substition are:

•%c to match the client id of the client

•%u to match the username of the client

The substitution pattern must be the only text for that level of hierarchy. Pattern ACLs apply to all users even if the "user" keyword has previously been given.

Example:

pattern write sensor/%u/data

Allow access for bridge connection messages:

pattern write $SYS/broker/connection/%c/state

If the first character of a line of the ACL file is a # it is treated as a comment.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded ACLs will be freed and reloaded. Existing subscriptions will be affected after the reload.

See also https://mosquitto.org/documentation/dynamic-security/

allow_anonymous [ true | false ]

Boolean value that determines whether clients that connect without providing a username are allowed to connect. If set to false then another means of connection should be created to control authenticated client access. Defaults to false, unless no listeners are defined in the configuration file, in which case it set to true, but connections are only allowed from the local machine.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Important

In version 1.6.x and earlier, this option defaulted to true unless there was another security option set.

Reloaded on reload signal.

allow_duplicate_messages [ true | false ]

This option is deprecated and will be removed in a future version. The behaviour will default to true. If a client is subscribed to multiple subscriptions that overlap, e.g. foo/# and foo/+/baz , then MQTT expects that when the broker receives a message on a topic that matches both subscriptions, such as foo/bar/baz, then the client should only receive the message once.

Mosquitto keeps track of which clients a message has been sent to in order to meet this requirement. This option allows this behaviour to be disabled, which may be useful if you have a large number of clients subscribed to the same set of topics and want to minimise memory usage.

It can be safely set to true if you know in advance that your clients will never have overlapping subscriptions, otherwise your clients must be able to correctly deal with duplicate messages even when then have QoS=2.

Defaults to true.

This option applies globally.

Reloaded on reload signal.

allow_zero_length_clientid [ true | false ]

MQTT 3.1.1 and MQTT 5 allow clients to connect with a zero length client id and have the broker generate a client id for them. Use this option to allow/disallow this behaviour. Defaults to true. See also the auto_id_prefix option.

If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal.

auth_plugin_deny_special_chars [ true | false ]

If true then before an ACL check is made, the username/client id of the client needing the check is searched for the presence of either a '+' or '#' character. If either of these characters is found in either the username or client id, then the ACL check is denied before it is sent to the plugin. This check prevents the case where a malicious user could circumvent an ACL check by using one of these characters as their username or client id. This is the same issue as was reported with mosquitto itself as CVE-2017-7650.

If you are entirely sure that the plugin you are using is not vulnerable to this attack (i.e. if you never use usernames or client ids in topics) then you can disable this extra check and hence have all ACL checks delivered to your plugin by setting this option to false.

Defaults to true.

Applies to the current authentication plugin being configured.

Not currently reloaded on reload signal.

auto_id_prefix prefix

If allow_zero_length_clientid is true, this option allows you to set a string that will be prefixed to the automatically generated client ids to aid visibility in logs. Defaults to auto-. If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal.

autosave_interval seconds

The number of seconds that mosquitto will wait between each time it saves the in-memory database to disk. If set to 0, the in-memory database will only be saved when mosquitto exits or when receiving the SIGUSR1 signal. Note that this setting only has an effect if persistence is enabled. Defaults to 1800 seconds (30 minutes). This option applies globally.

Reloaded on reload signal.

autosave_on_changes [ true | false ]

If true, mosquitto will count the number of subscription changes, retained messages received and queued messages and if the total exceeds autosave_interval then the in-memory database will be saved to disk. If false, mosquitto will save the in-memory database to disk by treating autosave_interval as a time in seconds. This option applies globally.

Reloaded on reload signal.

check_retain_source [ true | false ]

This option affects the scenario when a client subscribes to a topic that has retained messages. It is possible that the client that published the retained message to the topic had access at the time they published, but that access has been subsequently removed. If check_retain_source is set to true, the default, the source of a retained message will be checked for access rights before it is republished. When set to false, no check will be made and the retained message will always be published. This option applies globally, regardless of the per_listener_settings option.

clientid_prefixes prefix

This option is deprecated and will be removed in a future version. If defined, only clients that have a clientid with a prefix that matches clientid_prefixes will be allowed to connect to the broker. For example, setting "secure-" here would mean a client "secure-client" could connect but another with clientid "mqtt" couldn't. By default, all client ids are valid.

This option applies globally.

Reloaded on reload signal. Note that currently connected clients will be unaffected by any changes.

connection_messages [ true | false ]

If set to true, the log will include entries when clients connect and disconnect. If set to false, these entries will not appear. This option applies globally.

Reloaded on reload signal.

include_dir dir

External configuration files may be included by using the include_dir option. This defines a directory that will be searched for config files. All files that end in '.conf' will be loaded as a configuration file. It is best to have this as the last option in the main file. This option will only be processed from the main configuration file. The directory specified must not contain the main configuration file. The configuration files in include_dir are loaded in case sensitive alphabetical order, with the upper case of each letter ordered before the lower case of the same letter.

Example Load Order for include_dir. Given the files b.conf, A.conf, 01.conf, a.conf, B.conf, and 00.conf inside include_dir, the config files would be loaded in this order:

```
00.conf
01.conf
A.conf
a.conf
B.conf
b.conf
```

If this option is used multiple times, then each include_dir option is processed completely in the order that they are written in the main configuration file.

Example Load Order for Multiple include_dir. Assuming a directory one.d containing files B.conf and C.conf, and a second directory two.d containing files A.conf and D.conf, and a config:

```
include_dir one.d
include_dir two.d
```

Then the config files would be loaded in this order:

```
# files from one.d
B.conf
C.conf
# files from two.d
A.conf
D.conf
```

log_dest destinations

Send log messages to a particular destination. Possible destinations are: stdout stderr syslog topic file dlt. stdout and stderr log to the console on the named output.

syslog uses the userspace syslog facility which usually ends up in /var/log/messages or similar.

topic logs to the broker topic '$SYS/broker/log/<severity>', where severity is one of E, W, N, I, M which are error, warning, notice, information and message. Message type severity is used by the subscribe and unsubscribe log_type options and publishes log messages at $SYS/broker/log/M/subscribe and $SYS/broker/log/M/unsubscribe. Debug messages are never logged on topics.

The file destination requires an additional parameter which is the file to be logged to, e.g. "log_dest file /var/log/mosquitto.log". The file will be closed and reopened when the broker receives a HUP signal. Only a single file destination may be configured.

The dlt destination is for the automotive `Diagnostic Log and Trace` tool. This requires that Mosquitto has been compiled with DLT support.

Use "log_dest none" if you wish to disable logging. Defaults to stderr. This option may be specified multiple times.

Note that if the broker is running as a Windows service it will default to "log_dest none" and neither stdout nor stderr logging is available.

Reloaded on reload signal.

log_facility local facility

If using syslog logging (not on Windows), messages will be logged to the "daemon" facility by default. Use the log_facility option to choose which of local0 to local7 to log to instead. The option value should be an integer value, e.g. "log_facility 5" to use local5.

log_timestamp [ true | false ]

Boolean value, if set to true a timestamp value will be added to each log entry. The default is true. Reloaded on reload signal.

log_timestamp_format format

Set the format of the log timestamp. If left unset, this is the number of seconds since the Unix epoch. This option is a free text string which will be passed to the strftime function as the format specifier. To get an ISO 8601 datetime, for example:

```
log_timestamp_format %Y-%m-%dT%H:%M:%S

```

Reloaded on reload signal.

log_type types

Choose types of messages to log. Possible types are: debug, error, warning, notice, information, subscribe, unsubscribe, websockets, none, all. Defaults to error, warning, notice and information. This option may be specified multiple times. Note that the debug type (used for decoding incoming/outgoing network packets) is never logged in topics.

Reloaded on reload signal.

max_inflight_bytes count

Outgoing QoS 1 and 2 messages will be allowed in flight until this byte limit is reached. This allows control of outgoing message rate based on message size rather than message count. If the limit is set to 100, messages of over 100 bytes are still allowed, but only a single message can be in flight at once. Defaults to 0. (No limit). See also the max_inflight_messages option.

This option applies globally.

Reloaded on reload signal.

max_inflight_messages count

The maximum number of outgoing QoS 1 or 2 messages that can be in the process of being transmitted simultaneously. This includes messages currently going through handshakes and messages that are being retried. Defaults to 20. Set to 0 for no maximum. If set to 1, this will guarantee in-order delivery of messages. This option applies globally.

Reloaded on reload signal.

max_keepalive value

For MQTT v5 clients, it is possible to have the server send a "server keepalive" value that will override the keepalive value set by the client. This is intended to be used as a mechanism to say that the server will disconnect the client earlier than it anticipated, and that the client should use the new keepalive value. The max_keepalive option allows you to specify that clients may only connect with keepalive less than or equal to this value, otherwise they will be sent a server keepalive telling them to use max_keepalive. This only applies to MQTT v5 clients. The maximum value allowable, and default value, is 65535. Set to 0 to allow clients to set keepalive = 0, which means no keepalive checks are made and the client will never be disconnected by the broker if no messages are received. You should be very sure this is the behaviour that you want.

For MQTT v3.1.1 and v3.1 clients, there is no mechanism to tell the client what keepalive value they should use. If an MQTT v3.1.1 or v3.1 client specifies a keepalive time greater than max_keepalive they will be sent a CONNACK message with the "identifier rejected" reason code, and disconnected.

This option applies globally.

Reloaded on reload signal.

max_packet_size value

For MQTT v5 clients, it is possible to have the server send a "maximum packet size" value that will instruct the client it will not accept MQTT packets with size greater than value bytes. This applies to the full MQTT packet, not just the payload. Setting this option to a positive value will set the maximum packet size to that number of bytes. If a client sends a packet which is larger than this value, it will be disconnected. This applies to all clients regardless of the protocol version they are using, but v3.1.1 and earlier clients will of course not have received the maximum packet size information. Defaults to no limit. This option applies to all clients, not just those using MQTT v5, but it is not possible to notify clients using MQTT v3.1.1 or MQTT v3.1 of the limit.

Setting below 20 bytes is forbidden because it is likely to interfere with normal client operation even with small payloads.

This option applies globally.

Reloaded on reload signal.

max_queued_bytes count

The number of outgoing QoS 1 and 2 messages above those currently in-flight will be queued (per client) by the broker. Once this limit has been reached, subsequent messages will be silently dropped. This is an important option if you are sending messages at a high rate and/or have clients who are slow to respond or may be offline for extended periods of time. Defaults to 0. (No maximum). See also the max_queued_messages option. If both max_queued_messages and max_queued_bytes are specified, packets will be queued until the first limit is reached.

This option applies globally.

Reloaded on reload signal.

max_queued_messages count

The maximum number of QoS 1 or 2 messages to hold in the queue (per client) above those messages that are currently in flight. Defaults to 1000. Set to 0 for no maximum (not recommended). See also the queue_qos0_messages and max_queued_bytes options. This option applies globally.

Reloaded on reload signal.

memory_limit limit

This option sets the maximum number of heap memory bytes that the broker will allocate, and hence sets a hard limit on memory use by the broker. Memory requests that exceed this value will be denied. The effect will vary depending on what has been denied. If an incoming message is being processed, then the message will be dropped and the publishing client will be disconnected. If an outgoing message is being sent, then the individual message will be dropped and the receiving client will be disconnected. Defaults to no limit. This option is only available if memory tracking support is compiled in.

Reloaded on reload signal. Setting to a lower value and reloading will not result in memory being freed.

message_size_limit limit

This option sets the maximum publish payload size that the broker will allow. Received messages that exceed this size will not be accepted by the broker. This means that the message will not be forwarded on to subscribing clients, but the QoS flow will be completed for QoS 1 or QoS 2 messages. MQTT v5 clients using QoS 1 or QoS 2 will receive a PUBACK or PUBREC with the "implementation specific error" reason code. The default value is 0, which means that all valid MQTT messages are accepted. MQTT imposes a maximum payload size of 268435455 bytes.

This option applies globally.

Reloaded on reload signal.

password_file file path

Set the path to a password file. If defined, the contents of the file are used to control client access to the broker. The file can be created using the mosquitto_passwd(1) utility. If mosquitto is compiled without TLS support (it is recommended that TLS support is included), then the password file should be a text file with each line in the format "username:password", where the colon and password are optional but recommended. If allow_anonymous is set to false, only users defined in this file will be able to connect. Setting allow_anonymous to true when password_fileis defined is valid and could be used with acl_file to have e.g. read only guest/anonymous accounts and defined users that can publish. If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded username and password data will be freed and reloaded. Clients that are already connected will not be affected.

See also mosquitto_passwd(1) and https://mosquitto.org/documentation/dynamic-security/

per_listener_settings [ true | false ]

If true, then authentication and access control settings will be controlled on a per-listener basis. The following options are affected: password_file, acl_file, psk_file, allow_anonymous, allow_zero_length_clientid, auto_id_prefix. plugin, plugin_opt_*, Note that if set to true, then a durable client (i.e. with clean session set to false) that has disconnected will use the ACL settings defined for the listener that it was most recently connected to.

The default behaviour is for this to be set to false, which maintains the settings behaviour from previous versions of mosquitto.

Reloaded on reload signal.

persistence [ true | false ]

If true, connection, subscription and message data will be written to the disk in mosquitto.db at the location dictated by persistence_location. When mosquitto is restarted, it will reload the information stored in mosquitto.db. The data will be written to disk when mosquitto closes and also at periodic intervals as defined by autosave_interval. Writing of the persistence database may also be forced by sending mosquitto the SIGUSR1 signal. If false, the data will be stored in memory only. Defaults to false. The persistence file may change its format in a new version. The broker can currently read all old formats, but will only save in the latest format. It should always be safe to upgrade, but cautious users may wish to take a copy of the persistence file before installing a new version so that they can roll back to an earlier version if necessary.

This option applies globally.

Reloaded on reload signal.

persistence_file file name

The filename to use for the persistent database. Defaults to mosquitto.db. This option applies globally.

Reloaded on reload signal.

persistence_location path

The path where the persistence database should be stored. If not given, then the current directory is used. This option applies globally.

Reloaded on reload signal.

persistent_client_expiration duration

This option allows the session of persistent clients (those with clean session set to false) that are not currently connected to be removed if they do not reconnect within a certain time frame. This is a non-standard option in MQTT v3.1. MQTT v3.1.1 and v5.0 allow brokers to remove client sessions. Badly designed clients may set clean session to false whilst using a randomly generated client id. This leads to persistent clients that connect once and never reconnect. This option allows these clients to be removed. This option allows persistent clients (those with clean session set to false) to be removed if they do not reconnect within a certain time frame.

The expiration period should be an integer followed by one of h d w m y for hour, day, week, month and year respectively. For example:

•persistent_client_expiration 2m

•persistent_client_expiration 14d

•persistent_client_expiration 1y

As this is a non-standard option, the default if not set is to never expire persistent clients.

This option applies globally.

Reloaded on reload signal.

pid_file file path

Write a pid file to the file specified. If not given (the default), no pid file will be written. If the pid file cannot be written, mosquitto will exit. If mosquitto is being automatically started by an init script it will usually be required to write a pid file. This should then be configured as e.g. /var/run/mosquitto/mosquitto.pid

Not reloaded on reload signal.

plugin_opt_* value

Options to be passed to the most recent plugin defined in the configuration file. See the specific plugin instructions for details of what options are available. Applies to the current plugin being configured.

This is also available as the auth_opt_* option, but this use is deprecated and will be removed in a future version.

plugin file path

Specify an external module to use for authentication and access control. This allows custom username/password and access control functions to be created. Can be specified multiple times to load multiple plugins. The plugins will be processed in the order that they are specified.

If password_file, or acl_file are used in the config file alongsize plugin, the plugin checks will run after the built in checks.

Not currently reloaded on reload signal.

See also https://mosquitto.org/documentation/dynamic-security/

This is also available as the auth_plugin option, but this use is deprecated and will be removed in a future version.

psk_file file path

Set the path to a pre-shared-key file. This option requires a listener to be have PSK support enabled. If defined, the contents of the file are used to control client access to the broker. Each line should be in the format "identity:key", where the key is a hexadecimal string with no leading "0x". A client connecting to a listener that has PSK support enabled must provide a matching identity and PSK to allow the encrypted connection to proceed. If per_listener_settings is true, this option applies to the current listener being configured only. If per_listener_settings is false, this option applies to all listeners.

Reloaded on reload signal. The currently loaded identity and key data will be freed and reloaded. Clients that are already connected will not be affected.

queue_qos0_messages [ true | false ]

Set to true to queue messages with QoS 0 when a persistent client is disconnected. When bridges topics are configured with QoS level 1 or 2 incoming QoS 0 messages for these topics are also queued. These messages are included in the limit imposed by max_queued_messages. Defaults to false. Note that the MQTT v3.1.1 spec states that only QoS 1 and 2 messages should be saved in this situation so this is a non-standard option.

This option applies globally.

Reloaded on reload signal.

retain_available [ true | false ]

If set to false, then retained messages are not supported. Clients that send a message with the retain bit will be disconnected if this option is set to false. Defaults to true. This option applies globally.

Reloaded on reload signal.

set_tcp_nodelay [ true | false ]

If set to true, the TCP_NODELAY option will be set on client sockets to disable Nagle's algorithm. This has the effect of reducing latency of some messages at potentially increasing the number of TCP packets being sent. Defaults to false. This option applies globally.

Reloaded on reload signal.

sys_interval seconds

The integer number of seconds between updates of the $SYS subscription hierarchy, which provides status information about the broker. If unset, defaults to 10 seconds. Set to 0 to disable publishing the $SYS hierarchy completely.

This option applies globally.

Reloaded on reload signal.

upgrade_outgoing_qos [ true | false ]

The MQTT specification requires that the QoS of a message delivered to a subscriber is never upgraded to match the QoS of the subscription. Enabling this option changes this behaviour. If upgrade_outgoing_qos is set true, messages sent to a subscriber will always match the QoS of its subscription. This is a non-standard option not provided for by the spec. Defaults to false. This option applies globally.

Reloaded on reload signal.

user username

When run as root, change to this user and its primary group on startup. If set to "mosquitto" or left unset, and if the "mosquitto" user does not exist, then mosquitto will change to the "nobody" user instead. If this is set to another value and mosquitto is unable to change to this user and group, it will exit with an error. The user specified must have read/write access to the persistence database if it is to be written. If run as a non-root user, this setting has no effect. Defaults to mosquitto. This setting has no effect on Windows and so you should run mosquitto as the user you wish it to run as.

Not reloaded on reload signal.

## LISTENERS
The network ports that mosquitto listens on can be controlled using listeners. The default listener options can be overridden and further listeners can be created.

### General Options
bind_address address

This option is deprecated and will be removed in a future version. Use the listener instead. Listen for incoming network connections on the specified IP address/hostname only. This is useful to restrict access to certain network interfaces. To restrict access to mosquitto to the local host only, use "bind_address localhost". This only applies to the default listener. Use the listener option to control other listeners.

It is recommended to use an explicit listener rather than rely on the implicit default listener options like this.

Not reloaded on reload signal.

bind_interface device

Listen for incoming network connections only on the specified interface. This is similar to the bind_address option but is useful when an interface has multiple addresses or the address may change. If used at the same time as the bind_address for the default listener, or the bind address/host part of the listener, then bind_interface will take priority.

This option is not available on Windows.

Not reloaded on reload signal.

http_dir directory

When a listener is using the websockets protocol, it is possible to serve http data as well. Set http_dir to a directory which contains the files you wish to serve. If this option is not specified, then no normal http connections will be possible. Not reloaded on reload signal.

listener port [bind address/host/unix socket path]

Listen for incoming network connection on the specified port. A second optional argument allows the listener to be bound to a specific ip address/hostname. If this variable is used and neither the global bind_address nor port options are used then the default listener will not be started. The bind address/host option allows this listener to be bound to a specific IP address by passing an IP address or hostname. For websockets listeners, it is only possible to pass an IP address here.

On systems that support Unix Domain Sockets, this option can also be used to create a Unix socket rather than opening a TCP socket. In this case, the port must be set to 0, and the unix socket path must be given.

This option may be specified multiple times. See also the mount_point option.

Not reloaded on reload signal.

max_connections count

Limit the total number of clients connected for the current listener. Set to -1 to have "unlimited" connections. Note that other limits may be imposed that are outside the control of mosquitto. See e.g. limits.conf(). Not reloaded on reload signal.

max_qos value

Limit the QoS value allowed for clients connecting to this listener. Defaults to 2, which means any QoS can be used. Set to 0 or 1 to limit to those QoS values. This makes use of an MQTT v5 feature to notify clients of the limitation. MQTT v3.1.1 clients will not be aware of the limitation. Clients publishing to this listener with a too-high QoS will be disconnected. Not reloaded on reload signal.

max_topic_alias number

This option sets the maximum number topic aliases that an MQTT v5 client is allowed to create. This option applies per listener. Defaults to 10. Set to 0 to disallow topic aliases. The maximum value possible is 65535. Not reloaded on reload signal.

mount_point topic prefix

This option is used with the listener option to isolate groups of clients. When a client connects to a listener which uses this option, the string argument is attached to the start of all topics for this client. This prefix is removed when any messages are sent to the client. This means a client connected to a listener with mount point example can only see messages that are published in the topic hierarchy example and below. Not reloaded on reload signal.

port port number

This option is deprecated and will be removed in a future version. Use the listener instead. Set the network port for the default listener to listen on. Defaults to 1883.

Not reloaded on reload signal.

It is recommended to use an explicit listener rather than rely on the implicit default listener options like this.

protocol value

Set the protocol to accept for the current listener. Can be mqtt, the default, or websockets if available. Websockets support is currently disabled by default at compile time. Certificate based TLS may be used with websockets, except that only the cafile, certfile, keyfile, ciphers, and ciphers_tls1.3 options are supported.

Not reloaded on reload signal.

socket_domain [ ipv4 | ipv6 ]

By default, a listener will attempt to listen on all supported IP protocol versions. If you do not have an IPv4 or IPv6 interface you may wish to disable support for either of those protocol versions. In particular, note that due to the limitations of the websockets library, it will only ever attempt to open IPv6 sockets if IPv6 support is compiled in, and so will fail if IPv6 is not available. Set to ipv4 to force the listener to only use IPv4, or set to ipv6 to force the listener to only use IPv6. If you want support for both IPv4 and IPv6, then do not use the socket_domain option.

Not reloaded on reload signal.

use_username_as_clientid [ true | false ]

Set use_username_as_clientid to true to replace the clientid that a client connected with its username. This allows authentication to be tied to the clientid, which means that it is possible to prevent one client disconnecting another by using the same clientid. Defaults to false. If a client connects with no username it will be disconnected as not authorised when this option is set to true. Do not use in conjunction with clientid_prefixes.

This does not apply globally, but on a per-listener basis.

See also use_identity_as_username.

Not reloaded on reload signal.

websockets_log_level level

Change the websockets logging level. This is a global option, it is not possible to set per listener. This is an integer that is interpreted by libwebsockets as a bit mask for its lws_log_levels enum. See the libwebsockets documentation for more details. To use this option, log_type websockets must also be enabled. Defaults to 0.

websockets_headers_size size

Change the websockets headers size. This is a global option, it is not possible to set per listener. This option sets the size of the buffer used in the libwebsockets library when reading HTTP headers. If you are passing large header data such as cookies then you may need to increase this value. If left unset, or set to 0, then the default of 1024 bytes will be used.

### Certificate based SSL/TLS Support
The following options are available for all listeners to configure certificate based SSL support. See also "Pre-shared-key based SSL/TLS support".

cafile file path

cafile is used to define the path to a file containing the PEM encoded CA certificates that are trusted when checking incoming client certificates.

capath directory path

capath is used to define a directory that contains PEM encoded CA certificates that are trusted when checking incoming client certificates. For capath to work correctly, the certificates files must have ".pem" as the file ending and you must run "openssl rehash <path to capath>" each time you add/remove a certificate.

certfile file path

Path to the PEM encoded server certificate. This option and keyfile must be present to enable certificate based TLS encryption. The certificate pointed to by this option will be reloaded when Mosquitto receives a SIGHUP signal. This can be used to load new certificates prior to the existing ones expiring.

ciphers cipher:list

The list of allowed ciphers for this listener, for TLS v1.2 and earlier only, each separated with a colon. Available ciphers can be obtained using the "openssl ciphers" command.

ciphers_tls1.3 cipher:list

The list of allowed ciphersuites for this listener, for TLS v1.3, each separated with a colon.

crlfile file path

If you have require_certificate set to true, you can create a certificate revocation list file to revoke access to particular client certificates. If you have done this, use crlfile to point to the PEM encoded revocation file.

dhparamfile file path

To allow the use of ephemeral DH key exchange, which provides forward security, the listener must load DH parameters. This can be specified with the dhparamfile option. The dhparamfile can be generated with the command e.g.

```
openssl dhparam -out dhparam.pem 2048
```

keyfile file path

Path to the PEM encoded server key. This option and certfile must be present to enable certificate based TLS encryption. The private key pointed to by this option will be reloaded when Mosquitto receives a SIGHUP signal. This can be used to load new keys prior to the existing ones expiring.

require_certificate [ true | false ]

By default an SSL/TLS enabled listener will operate in a similar fashion to a https enabled web server, in that the server has a certificate signed by a CA and the client will verify that it is a trusted certificate. The overall aim is encryption of the network traffic. By setting require_certificate to true, a client connecting to this listener must provide a valid certificate in order for the network connection to proceed. This allows access to the broker to be controlled outside of the mechanisms provided by MQTT.

tls_engine engine

A valid openssl engine id. These can be listed with openssl engine command.

tls_engine_kpass_sha1 engine_kpass_sha1

SHA1 of the private key password when using an TLS engine. Some TLS engines such as the TPM engine may require the use of a password in order to be accessed. This option allows a hex encoded SHA1 hash of the password to the engine directly, instead of the user being prompted for the password.

tls_keyform [ pem | engine ]

Specifies the type of private key in use when making TLS connections.. This can be "pem" or "engine". This parameter is useful when a TPM module is being used and the private key has been created with it. Defaults to "pem", which means normal private key files are used.

tls_version version

Configure the minimum version of the TLS protocol to be used for this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If left unset, the default of allowing TLS v1.3 and v1.2. In Mosquitto version 1.6.x and earlier, this option set the only TLS protocol version that was allowed, rather than the minimum.

use_identity_as_username [ true | false ]

If require_certificate is true, you may set use_identity_as_username to true to use the CN value from the client certificate as a username. If this is true, the password_file option will not be used for this listener. This takes priority over use_subject_as_username if both are set to true.

See also use_subject_as_username

use_subject_as_username [ true | false ]

If require_certificate is true, you may set use_subject_as_username to true to use the complete subject value from the client certificate as a username. If this is true, the password_file option will not be used for this listener. The subject will be generated in a form similar to CN=test client,OU=Production,O=Server,L=Nottingham,ST=Nottinghamshire,C=GB.

See also use_identity_as_username

### Pre-shared-key based SSL/TLS Support
The following options are available for all listeners to configure pre-shared-key based SSL support. See also "Certificate based SSL/TLS support".

ciphers cipher:list

When using PSK, the encryption ciphers used will be chosen from the list of available PSK ciphers. If you want to control which ciphers are available, use this option. The list of available ciphers can be optained using the "openssl ciphers" command and should be provided in the same format as the output of that command.

psk_hint hint

The psk_hint option enables pre-shared-key support for this listener and also acts as an identifier for this listener. The hint is sent to clients and may be used locally to aid authentication. The hint is a free form string that doesn't have much meaning in itself, so feel free to be creative. If this option is provided, see psk_file to define the pre-shared keys to be used or create a security plugin to handle them.

tls_version version

Configure the minimum version of the TLS protocol to be used for this listener. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. If left unset, the default of allowing TLS v1.3 and v1.2. In Mosquitto version 1.6.x and earlier, this option set the only TLS protocol version that was allowed, rather than the minimum.

use_identity_as_username [ true | false ]

Set use_identity_as_username to have the psk identity sent by the client used as its username. The username will be checked as normal, so password_file or another means of authentication checking must be used. No password will be used.

## CONFIGURING BRIDGES
Multiple bridges (connections to other brokers) can be configured using the following variables.

Bridges cannot currently be reloaded on reload signal.

address address[:port] [address[:port]], addresses address[:port] [address[:port]]

Specify the address and optionally the port of the bridge to connect to. This must be given for each bridge connection. If the port is not specified, the default of 1883 is used. If you use an IPv6 address, then the port is not optional.

Multiple host addresses can be specified on the address config. See the round_robin option for more details on the behaviour of bridges with multiple addresses.

bridge_attempt_unsubscribe [ true | false ]

If a bridge has topics that have "out" direction, the default behaviour is to send an unsubscribe request to the remote broker on that topic. This means that changing a topic direction from "in" to "out" will not keep receiving incoming messages. Sending these unsubscribe requests is not always desirable, setting bridge_attempt_unsubscribe to false will disable sending the unsubscribe request. Defaults to true.

bridge_bind_address ip address

If you need to have the bridge connect over a particular network interface, use bridge_bind_address to tell the bridge which local IP address the socket should bind to, e.g. bridge_bind_address 192.168.1.10.

bridge_max_packet_size value

If you wish to restrict the size of messages sent to a remote bridge, use this option. This sets the maximum number of bytes for the total message, including headers and payload. Note that MQTT v5 brokers may provide their own maximum-packet-size property. In this case, the smaller of the two limits will be used. Set to 0 for "unlimited".

bridge_outgoing_retain [ true | false ]

Some MQTT brokers do not allow retained messages. MQTT v5 gives a mechanism for brokers to tell clients that they do not support retained messages, but this is not possible for MQTT v3.1.1 or v3.1. If you need to bridge to a v3.1.1 or v3.1 broker that does not support retained messages, set the bridge_outgoing_retain option to false. This will remove the retain bit on all outgoing messages to that bridge, regardless of any other setting. Defaults to true.

bridge_protocol_version version

Set the version of the MQTT protocol to use with for this bridge. Can be one of mqttv50, mqttv311 or mqttv31. Defaults to mqttv311.

cleansession [ true | false ]

Set the clean session option for this bridge. Setting to false (the default), means that all subscriptions on the remote broker are kept in case of the network connection dropping. If set to true, all subscriptions and messages on the remote broker will be cleaned up if the connection drops. Note that setting to true may cause a large amount of retained messages to be sent each time the bridge reconnects. If you are using bridges with cleansession set to false (the default), then you may get unexpected behaviour from incoming topics if you change what topics you are subscribing to. This is because the remote broker keeps the subscription for the old topic. If you have this problem, connect your bridge with cleansession set to true, then reconnect with cleansession set to false as normal.

local_cleansession [ true | false]

The regular cleansession covers both the local subscriptions and the remote subscriptions. local_cleansession allows splitting this. Setting false will mean that the local connection will preserve subscription, independent of the remote connection. Defaults to the value of bridge.cleansession unless explicitly specified.

connection name

This variable marks the start of a new bridge connection. It is also used to give the bridge a name which is used as the client id on the remote broker.

keepalive_interval seconds

Set the number of seconds after which the bridge should send a ping if no other traffic has occurred. Defaults to 60. A minimum value of 5 seconds is allowed.

idle_timeout seconds

Set the amount of time a bridge using the lazy start type must be idle before it will be stopped. Defaults to 60 seconds.

local_clientid id

Set the clientid to use on the local broker. If not defined, this defaults to local.<remote_clientid>. If you are bridging a broker to itself, it is important that local_clientid and remote_clientid do not match.

local_password password

Configure the password to be used when connecting this bridge to the local broker. This may be important when authentication and ACLs are being used.

local_username username

Configure the username to be used when connecting this bridge to the local broker. This may be important when authentication and ACLs are being used.

notifications [ true | false ]

If set to true, publish notification messages to the local and remote brokers giving information about the state of the bridge connection. Retained messages are published to the topic $SYS/broker/connection/<remote_clientid>/state unless otherwise set with notification_topics. If the message is 1 then the connection is active, or 0 if the connection has failed. Defaults to true. This uses the Last Will and Testament (LWT) feature.

notifications_local_only [ true | false ]

If set to true, only publish notification messages to the local broker giving information about the state of the bridge connection. Defaults to false.

notification_topic topic

Choose the topic on which notifications will be published for this bridge. If not set the messages will be sent on the topic $SYS/broker/connection/<remote_clientid>/state.

remote_clientid id

Set the client id for this bridge connection. If not defined, this defaults to 'name.hostname', where name is the connection name and hostname is the hostname of this computer. This replaces the old "clientid" option to avoid confusion with local/remote sides of the bridge. "clientid" remains valid for the time being.

remote_password value

Configure a password for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT v3.1 and up and requires a username and/or password to connect. This option is only valid if a remote_username is also supplied. This replaces the old "password" option to avoid confusion with local/remote sides of the bridge. "password" remains valid for the time being.

remote_username name

Configure a username for the bridge. This is used for authentication purposes when connecting to a broker that supports MQTT v3.1 and up and requires a username and/or password to connect. See also the remote_password option. This replaces the old "username" option to avoid confusion with local/remote sides of the bridge. "username" remains valid for the time being.

restart_timeout base cap, restart_timeout constant

Set the amount of time a bridge using the automatic start type will wait until attempting to reconnect. This option can be configured to use a constant delay time in seconds, or to use a backoff mechanism based on "Decorrelated Jitter", which adds a degree of randomness to when the restart occurs, starting at the base and increasing up to the cap. Set a constant timeout of 20 seconds:

```
restart_timeout 20
```

Set backoff with a base (start value) of 10 seconds and a cap (upper limit) of 60 seconds:

```
restart_timeout 10 30
```

Defaults to jitter with a base of 5 seconds and cap of 30 seconds.

round_robin [ true | false ]

If the bridge has more than one address given in the address/addresses configuration, the round_robin option defines the behaviour of the bridge on a failure of the bridge connection. If round_robin is false, the default value, then the first address is treated as the main bridge connection. If the connection fails, the other secondary addresses will be attempted in turn. Whilst connected to a secondary bridge, the bridge will periodically attempt to reconnect to the main bridge until successful. If round_robin is true, then all addresses are treated as equals. If a connection fails, the next address will be tried and if successful will remain connected until it fails.

start_type [ automatic | lazy | once ]

Set the start type of the bridge. This controls how the bridge starts and can be one of three types: automatic, lazy and once. Note that RSMB provides a fourth start type "manual" which isn't currently supported by mosquitto. automatic is the default start type and means that the bridge connection will be started automatically when the broker starts and also restarted after a short delay (30 seconds) if the connection fails.

Bridges using the lazy start type will be started automatically when the number of queued messages exceeds the number set with the threshold option. It will be stopped automatically after the time set by the idle_timeout parameter. Use this start type if you wish the connection to only be active when it is needed.

A bridge using the once start type will be started automatically when the broker starts but will not be restarted if the connection fails.

threshold count

Set the number of messages that need to be queued for a bridge with lazy start type to be restarted. Defaults to 10 messages.

topic pattern [[[ out | in | both ] qos-level] local-prefix remote-prefix]

Define a topic pattern to be shared between the two brokers. Any topics matching the pattern (which may include wildcards) are shared. The second parameter defines the direction that the messages will be shared in, so it is possible to import messages from a remote broker using in, export messages to a remote broker using out or share messages in both directions. If this parameter is not defined, the default of out is used. The QoS level defines the publish/subscribe QoS level used for this topic and defaults to 0. The local-prefix and remote-prefix options allow topics to be remapped when publishing to and receiving from remote brokers. This allows a topic tree from the local broker to be inserted into the topic tree of the remote broker at an appropriate place.

For incoming topics, the bridge will prepend the pattern with the remote prefix and subscribe to the resulting topic on the remote broker. When a matching incoming message is received, the remote prefix will be removed from the topic and then the local prefix added.

For outgoing topics, the bridge will prepend the pattern with the local prefix and subscribe to the resulting topic on the local broker. When an outgoing message is processed, the local prefix will be removed from the topic then the remote prefix added.

When using topic mapping, an empty prefix can be defined using the place marker "". Using the empty marker for the topic itself is also valid. The table below defines what combination of empty or value is valid. The Full Local Topic and Full Remote Topic show the resulting topics that would be used on the local and remote ends of the bridge. For example, for the first table row if you publish to L/topic on the local broker, then the remote broker will receive a message on the topic R/topic.

Pattern

Local Prefix

Remote Prefix

Validity

Full Local Topic

Full Remote Topic

pattern

L/

R/

valid

L/pattern

R/pattern

pattern

L/

""

valid

L/pattern

pattern

pattern

""

R/

valid

pattern

R/pattern

pattern

""

""

valid (no remapping)

pattern

pattern

""

local

remote

valid (remap single local topic to remote)

local

remote

""

local

""

invalid

""

""

remote

invalid

""

""

""

invalid

To remap an entire topic tree, use e.g.:

```
topic # both 2 local/topic/ remote/topic/
```

This option can be specified multiple times per bridge.

Care must be taken to ensure that loops are not created with this option. If you are experiencing high CPU load from a broker, it is possible that you have a loop where each broker is forever forwarding each other the same messages.

See also the cleansession option if you have messages arriving on unexpected topics when using incoming topics.

Example Bridge Topic Remapping. The configuration below connects a bridge to the broker at test.mosquitto.org. It subscribes to the remote topic $SYS/broker/clients/total and republishes the messages received to the local topic test/mosquitto/org/clients/total

```
connection test-mosquitto-org
address test.mosquitto.org
cleansession true
topic clients/total in 0 test/mosquitto/org/ $SYS/broker/
```

try_private [ true | false ]

If try_private is set to true, the bridge will attempt to indicate to the remote broker that it is a bridge not an ordinary client. If successful, this means that loop detection will be more effective and that retained messages will be propagated correctly. Not all brokers support this feature so it may be necessary to set try_private to false if your bridge does not connect properly. Defaults to true.

### SSL/TLS Support
The following options are available for all bridges to configure SSL/TLS support.

bridge_alpn alpn

Configure the application layer protocol negotiation option for the TLS session. Useful for brokers that support both websockets and MQTT on the same port.

bridge_cafile file path

One of bridge_cafile or bridge_capath must be provided to allow SSL/TLS support. bridge_cafile is used to define the path to a file containing the PEM encoded CA certificates that have signed the certificate for the remote broker.

bridge_capath file path

One of bridge_capath or bridge_cafile must be provided to allow SSL/TLS support. bridge_capath is used to define the path to a directory containing the PEM encoded CA certificates that have signed the certificate for the remote broker. For bridge_capath to work correctly, the certificate files must have ".crt" as the file ending and you must run "openssl rehash <path to bridge_capath>" each time you add/remove a certificate.

bridge_certfile file path

Path to the PEM encoded client certificate for this bridge, if required by the remote broker.

bridge_identity identity

Pre-shared-key encryption provides an alternative to certificate based encryption. A bridge can be configured to use PSK with the bridge_identity and bridge_psk options. This is the client identity used with PSK encryption. Only one of certificate and PSK based encryption can be used on one bridge at once.

bridge_insecure [ true | false ]

When using certificate based TLS, the bridge will attempt to verify the hostname provided in the remote certificate matches the host/address being connected to. This may cause problems in testing scenarios, so bridge_insecure may be set to true to disable the hostname verification. Setting this option to true means that a malicious third party could potentially impersonate your server, so it should always be set to false in production environments.

bridge_keyfile file path

Path to the PEM encoded private key for this bridge, if required by the remote broker.

bridge_psk key

Pre-shared-key encryption provides an alternative to certificate based encryption. A bridge can be configured to use PSK with the bridge_identity and bridge_psk options. This is the pre-shared-key in hexadecimal format with no "0x". Only one of certificate and PSK based encryption can be used on one bridge at once.

bridge_require_ocsp [ true | false ]

When set to true, the bridge requires OCSP on the TLS connection it opens as client.

bridge_tls_version version

Configure the version of the TLS protocol to be used for this bridge. Possible values are tlsv1.3, tlsv1.2 and tlsv1.1. Defaults to tlsv1.2. The remote broker must support the same version of TLS for the connection to succeed.

## FILES
mosquitto.conf

## BUGS
mosquitto bug information can be found at https://github.com/eclipse/mosquitto/issues

## SEE ALSO
mosquitto(8), mosquitto_passwd(1), mosquitto-tls(7), mqtt(7), limits.conf(5)

## AUTHOR
Roger Light <roger@atchoo.org>


fstab

package: mount

title: fstab(5)

text:
# fstab(5)

## NAME
fstab - static information about the filesystems

## SYNOPSIS
/etc/fstab

## DESCRIPTION
The file fstab contains descriptive information about the filesystems the system can mount. fstab is only read by programs, and not written; it is the duty of the system administrator to properly create and maintain this file. The order of records in fstab is important because fsck(8), mount(8), and umount(8) sequentially iterate through fstab doing their thing.

Each filesystem is described on a separate line. Fields on each line are separated by tabs or spaces. Lines starting with '#' are comments. Blank lines are ignored.

The following is a typical example of an fstab entry:

```
LABEL=t-home2   /home      ext4    defaults,auto_da_alloc      0  2
```

### The first field (fs_spec).
This field describes the block special device, remote filesystem or filesystem image for loop device to be mounted or swap file or swap device to be enabled.

For ordinary mounts, it will hold (a link to) a block special device node (as created by mknod(2)) for the device to be mounted, like /dev/cdrom or /dev/sdb7. For NFS mounts, this field is <host>:<dir>, e.g., knuth.aeb.nl:/. For filesystems with no storage, any string can be used, and will show up in df(1) output, for example. Typical usage is proc for procfs; mem, none, or tmpfs for tmpfs. Other special filesystems, like udev and sysfs, are typically not listed in fstab.

LABEL=<label> or UUID=<uuid> may be given instead of a device name. This is the recommended method, as device names are often a coincidence of hardware detection order, and can change when other disks are added or removed. For example, 'LABEL=Boot' or 'UUID=3e6be9de-8139-11d1-9106-a43f08d823a6'. (Use a filesystem-specific tool like e2label(8), xfs_admin(8), or fatlabel(8) to set LABELs on filesystems).

It’s also possible to use PARTUUID= and PARTLABEL=. These partitions identifiers are supported for example for GUID Partition Table (GPT).

See mount(8), blkid(8) or lsblk(8) for more details about device identifiers.

Note that mount(8) uses UUIDs as strings. The string representation of the UUID should be based on lower case characters. But when specifying the volume ID of FAT or NTFS file systems upper case characters are used (e.g UUID="A40D-85E7" or UUID="61DB7756DB7779B3").

### The second field (fs_file).
This field describes the mount point (target) for the filesystem. For swap area, this field should be specified as `none'. If the name of the mount point contains spaces or tabs these can be escaped as `\040' and '\011' respectively.

### The third field (fs_vfstype).
This field describes the type of the filesystem. Linux supports many filesystem types: ext4, xfs, btrfs, f2fs, vfat, ntfs, hfsplus, tmpfs, sysfs, proc, iso9660, udf, squashfs, nfs, cifs, and many more. For more details, see mount(8).

An entry swap denotes a file or partition to be used for swapping, cf. swapon(8). An entry none is useful for bind or move mounts.

More than one type may be specified in a comma-separated list.

mount(8) and umount(8) support filesystem subtypes. The subtype is defined by '.subtype' suffix. For example 'fuse.sshfs'. It’s recommended to use subtype notation rather than add any prefix to the first fstab field (for example 'sshfs#example.com' is deprecated).

### The fourth field (fs_mntops).
This field describes the mount options associated with the filesystem.

It is formatted as a comma-separated list of options and is optional for mount(8) or swapon(8). The usual convention is to use at least "defaults" keyword there.

It usually contains the type of mount (ro or rw, the default is rw), plus any additional options appropriate to the filesystem type (including performance-tuning options). For details, see mount(8) or swapon(8).

Basic filesystem-independent options are:

defaults

use default options. The default depends on the kernel and the filesystem. mount(8) does not have any hardcoded set of default options. The kernel default is usually rw, suid, dev, exec, auto, nouser, and async.

noauto

do not mount when mount -a is given (e.g., at boot time)

user

allow a user to mount

owner

allow device owner to mount

comment

or x-<name> for use by fstab-maintaining programs

nofail

do not report errors for this device if it does not exist.

### The fifth field (fs_freq).
This field is used by dump(8) to determine which filesystems need to be dumped. Defaults to zero (don’t dump) if not present.

### The sixth field (fs_passno).
This field is used by fsck(8) to determine the order in which filesystem checks are done at boot time. The root filesystem should be specified with a fs_passno of 1. Other filesystems should have a fs_passno of 2. Filesystems within a drive will be checked sequentially, but filesystems on different drives will be checked at the same time to utilize parallelism available in the hardware. Defaults to zero (don’t check the filesystem) if not present.

## FILES
/etc/fstab, <fstab.h>

## NOTES
The proper way to read records from fstab is to use the routines getmntent(3) or libmount.

The keyword ignore as a filesystem type (3rd field) is no longer supported by the pure libmount based mount utility (since util-linux v2.22).

## HISTORY
The ancestor of this fstab file format appeared in 4.0BSD.

## SEE ALSO
getmntent(3), fs(5), findmnt(8), mount(8), swapon(8)

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

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


mpd.conf

package: mpd

title: mpd.conf(5)

summary: mpd.conf documentation

text:
# mpd.conf(5)

## NAME
mpd.conf - mpd.conf documentation

## DESCRIPTION
mpd.conf is the configuration file for mpd(1). If not specified on the command line, MPD first searches for it at $XDG_CONFIG_HOME/mpd/mpd.conf then at ~/.mpdconf then at ~/.mpd/mpd.conf and then in /etc/mpd.conf.

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

connection_timeout "5"

Lines starting with # are treated as comments and ignored.

For settings that specify a file system path, the tilde ('~') is expanded to $HOME. In addition, the following path expansions are supported:

- $HOME

- $XDG_CONFIG_HOME

- $XDG_MUSIC_DIR

- $XDG_CACHE_HOME

- $XDG_RUNTIME_DIR

music_directory "~/Music"

db_file "$XDG_CONFIG_HOME/mpd/database"

Some of the settings are grouped in blocks with curly braces, e.g. per-plugin settings:

```
audio_output {

    type "alsa"

    name "My ALSA output"

    device "iec958:CARD=Intel,DEV=0"

    mixer_control "PCM"
}
```

The include directive can be used to include settings from another file; the given file name is relative to the current file:

include "other.conf"

You can use include_optional instead if you want the included file to be optional; the directive will be ignored if the file does not exist:

include_optional "may_not_exist.conf"

See docs/mpdconf.example in the source tarball for an example configuration file.

This manual is not complete, it lists only the most important options. Please read the MPD user manual for a complete configuration guide: http://www.musicpd.org/doc/user/

## OPTIONAL PARAMETERS
db_file <file>

This specifies where the db file will be stored.

log_file <file>

This specifies where the log file should be located. The special value "syslog" makes MPD use the local syslog daemon.

sticker_file <file>

The location of the sticker database. This is a database which manages dynamic information attached to songs.

pid_file <file>

This specifies the file to save mpd's process ID in.

music_directory <directory>

This specifies the directory where music is located. If you do not configure this, you can only play streams.

playlist_directory <directory>

This specifies the directory where saved playlists are stored. If you do not configure this, you cannot save playlists.

state_file <file>

This specifies if a state file is used and where it is located. The state of mpd will be saved to this file when mpd is terminated by a TERM signal or by the kill command. When mpd is restarted, it will read the state file and restore the state of mpd (including the playlist).

restore_paused <yes or no>

Put MPD into pause mode instead of starting playback after startup.

user <username>

This specifies the user that MPD will run as, if set. MPD should never run as root, and you may use this option to make MPD change its user id after initialization. Do not use this option if you start MPD as an unprivileged user.

port <port>

This specifies the port that mpd listens on. The default is 6600.

log_level <level>

Suppress all messages below the given threshold. The following log levels are available:

- error: errors

- warning: warnings

- notice: interesting informational messages

- info: unimportant informational messages

- verbose: debug messages (for developers and for troubleshooting)

The default is notice.

follow_outside_symlinks <yes or no>

Control if MPD will follow symbolic links pointing outside the music dir. You must recreate the database after changing this option. The default is "yes".

follow_inside_symlinks <yes or no>

Control if MPD will follow symbolic links pointing inside the music dir, potentially adding duplicates to the database. You must recreate the database after changing this option. The default is "yes".

zeroconf_enabled <yes or no>

If yes, and MPD has been compiled with support for Avahi or Bonjour, service information will be published with Zeroconf. The default is yes.

zeroconf_name <name>

If Zeroconf is enabled, this is the service name to publish. This name should be unique to your local network, but name collisions will be properly dealt with. The default is "Music Player @ %h", where %h will be replaced with the hostname of the machine running MPD.

audio_output

See DESCRIPTION and the various AUDIO OUTPUT PARAMETERS sections for the format of this parameter. Multiple audio_output sections may be specified. If no audio_output section is specified, then MPD will scan for a usable audio output.

filesystem_charset <charset>

This specifies the character set used for the filesystem. A list of supported character sets can be obtained by running "iconv -l". The default is determined from the locale when the db was originally created.

save_absolute_paths_in_playlists <yes or no>

This specifies whether relative or absolute paths for song filenames are used when saving playlists. The default is "no".

auto_update <yes or no>

This specifies the whether to support automatic update of music database when files are changed in music_directory. The default is to disable autoupdate of database. (Only implemented on Linux.)

auto_update_depth <N>

Limit the depth of the directories being watched, 0 means only watch the music directory itself. There is no limit by default.

## REQUIRED AUDIO OUTPUT PARAMETERS
type <type>

This specifies the audio output type. See the list of supported outputs in mpd --version for possible values.

name <name>

This specifies a unique name for the audio output.

## OPTIONAL AUDIO OUTPUT PARAMETERS
format <sample_rate:bits:channels>

This specifies the sample rate, bits per sample, and number of channels of audio that is sent to the audio output device. See documentation for the audio_output_format parameter for more details. The default is to use whatever audio format is passed to the audio output. Any of the three attributes may be an asterisk to specify that this attribute should not be enforced

replay_gain_handler <software, mixer or none>

Specifies how replay gain is applied. The default is "software", which uses an internal software volume control. "mixer" uses the configured (hardware) mixer control. "none" disables replay gain on this audio output.

mixer_type <hardware, software or none>

Specifies which mixer should be used for this audio output: the hardware mixer (available for ALSA, OSS and PulseAudio), the software mixer or no mixer ("none"). By default, the hardware mixer is used for devices which support it, and none for the others.

## FILES
$XDG_CONFIG_HOME/mpd/mpd.conf

User configuration file (usually ~/.config/mpd/mpd.conf).

/etc/mpd.conf

Global configuration file.

## SEE ALSO
mpd(1), mpc(1)

## AUTHOR
Max Kellermann

## COPYRIGHT
2003-2025 The Music Player Daemon Project


mstpctl-utils-interfaces

package: mstpd

title: mstpctl-utils-interfaces(5)

summary: mstpctl-utils extensions for the

text:
# mstpctl-utils-interfaces(5)

## NAME
mstpctl-utils-interfaces - mstpctl-utils extensions for the interfaces(5) file format

## DESCRIPTION
/etc/network/interfaces contains network interface configuration information for the ifup(8) and ifdown(8) commands. This manpage describes the mstpctl extensions to the standard interfaces(5) file format.

The main extension is the mstpctl_ports option, with it you describe that the interface is a bridge and what ports does it have. Spanning Tree protocol parameters can also be specified. Currently multiple spanning trees are not supported by this extension (although mstpd/mstpctl supports MSTP without restrictions). This means that all settings here are applied to the CIST tree.

We'll see this with an example:

```
auto br0
iface br0 inet static

    address 12.0.0.3

    netmask 255.255.255.0

    mstpctl_ports swp1 swp2 swp3 swp4

    mstpctl_stp on

    mstpctl_maxwait auto

    mstpctl_maxage 20

    mstpctl_fdelay 15

    mstpctl_maxhops 20

    mstpctl_txholdcount 6

    mstpctl_forcevers rstp

    mstpctl_portpathcost swp1=0 swp2=0

    mstpctl_portadminedge swp1=no swp2=no swp4=yes

    mstpctl_portautoedge swp1=yes swp2=yes

    mstpctl_portp2p swp1=no swp2=no

    mstpctl_portrestrrole swp1=no swp2=no

    mstpctl_bpduguard swp1=no swp2=no swp4=yes

    mstpctl_portrestrtcn swp1=no swp2=no

    mstpctl_treeprio 8

    mstpctl_treeportprio swp3=8

    mstpctl_hello 2

    mstpctl_portnetwork swp1=no

    mstpctl_portbpdufilter swp4=yes
```

## IFACE OPTIONS
The below interface options for configuring STP parameters on an STP enabled bridge can be specified in /etc/network/interfaces.

mstpctl_ports interface specification

this option must exist to specify the bridge and the ports which need to be added to the bridge.

```
mstpctl_ports swp1 swp4
```

Regular expressions can be used to select a number of interfaces

```
mstpctl_ports regex (eth|vif).*
```

This means to evaluate (as in egrep(1)) the expressions that follow after "regex" until either the end or a "noregex" statement is reached.

mstpctl_stp yes|no

turn spanning tree protocol on/off, default is no.

mstpctl_maxwait time|auto

set max time in seconds to wait for initial STP convergence before allowing ifup to exit, default is auto (=fdelay*2+1).

mstpctl_maxage time

set max message age to time seconds, default is 20.

mstpctl_fdelay time

set bridge forward delay to time seconds, default is 15.

mstpctl_maxhops max_hops

set bridge maximum hops to max_hops, default is 20.

mstpctl_forcevers mstp|rstp|stp

forces the bridge to use specific STP protocol version. mstp is the default.

mstpctl_txholdcount tx_hold_count

set bridge transmit hold count to tx_hold_count, default is 6.

mstpctl_treeprio priority

set bridge tree priority, priority is between 0 and 15. Bridge priority affects bridge id, lowest priority bridge will be the root. Note that traditionally bridge priority is a multiple of 4096 and ranges from 0 to 15*4096 = 61440. mstpd is different - it throws out that useless "multiple of 4096" rule and expresses bridge priority in natural units (0-15). Default is 8.

mstpctl_portpathcost port cost

set path cost for a port, default is 0 (= auto), port is the name of the interface to which this setting applies.

mstpctl_portadminedge port yes|no

Enables/disables the admin edge state of the port, default is no.

mstpctl_portautoedge port yes|no

Enables/disables the auto transition to/from edge state of the port, default is yes.

mstpctl_portp2p port yes|no|auto

Enables/disables the point2point detection mode of the port, default is auto.

mstpctl_portrestrrole port yes|no

Enables/disables the restrictions on the port's ability to take root role, default is no (i.e. no restrictions on the port's role).

mstpctl_portrestrtcn port yes|no

Enables/disables the restrictions on the port's ability to propagate received topology change notification, default is no (i.e. no restrictions on the TCN propagation).

mstpctl_bpduguard port yes|no

Enables/disables the bpduguard configuration of the port, default is no.

mstpctl_treeportprio port priority

sets the port's priority to priority. The priority value is a number between 0 and 15. Note that traditionally port priority is a multiple of 16 and ranges from 0 to 15*16 = 240. mstpd is different - it throws out that useless "multiple of 16" rule and expresses port priority in natural units (0-15). Default is 8.

mstpctl_hello time

set hello time to time seconds, default is 2.

mstpctl_ageing time

sets the ethernet (MAC) address ageing time, in seconds. Used only when protocol version is forced to STP, default is 300s. Note that this parameter differs from the other ones: it is only informational parameter. By setting it in the mstpd one do not change the real bridge's Ageing Time; it is supposed to be set as information to the mstpd that real Ageing Time in the real bridge was changed.

mstpctl_portnetwork port yes|no

Enables/disables the bridge assurance capability for a port, default is no.

mstpctl_portbpdufilter port yes|no

Enables/disables the bridge BPDU filter capability for a port, default is no.

## FILES
/etc/network/interfaces

definitions of network interfaces See interfaces(5) for more information.

## AUTHOR
This manpage was written by Satish Ashok <sashok@cumulusnetworks.com> based on brctl-utils-interfaces(5).

## SEE ALSO
brctl(8), interfaces(5), ifup(8), iwconfig(8), run-parts(8).


mtools

package: mtools

title: mtools(5)

text:
# mtools(5)

## Name
mtools.conf - mtools configuration files

## Description
This manual page describes the configuration files for mtools. They are called `/etc/mtools.conf' and `~/.mtoolsrc'. If the environmental variable MTOOLSRC is set, its contents is used as the filename for a third configuration file. These configuration files describe the following items:

* Global configuration flags and variables

* Per drive flags and variables

### Location of the configuration files
`/etc/mtools.conf' is the system-wide configuration file, and `~/.mtoolsrc' is the user's private configuration file.

On some systems, the system-wide configuration file is called `/etc/default/mtools.conf' instead.

###  General configuration file syntax
The configuration files is made up of sections. Each section starts with a keyword identifying the section followed by a colon. Then follow variable assignments and flags. Variable assignments take the following form:

```
name=value
```

Flags are lone keywords without an equal sign and value following them. A section either ends at the end of the file or where the next section begins.

Lines starting with a hash (#) are comments. Newline characters are equivalent to whitespace (except where ending a comment). The configuration file is case insensitive, except for item enclosed in quotes (such as filenames).

### Default values
For most platforms, mtools contains reasonable compiled-in defaults for physical floppy drives. Thus, you usually don't need to bother with the configuration file, if all you want to do with mtools is to access your floppy drives. On the other hand, the configuration file is needed if you also want to use mtools to access your hard disk partitions and DOSEMU image files.

### Global variables
Global flags may be set to 1 or to 0.

The following global flags are recognized:

MTOOLS_SKIP_CHECK

If this is set to 1, mtools skips most of its sanity checks. This is needed to read some Atari disks which have been made with the earlier ROMs, and which would not be recognized otherwise.

MTOOLS_FAT_COMPATIBILITY

If this is set to 1, mtools skips the fat size checks. Some disks have a bigger FAT than they really need to. These are rejected if this option is not set.

MTOOLS_LOWER_CASE

If this is set to 1, mtools displays all-upper-case short filenames as lowercase. This has been done to allow a behavior which is consistent with older versions of mtools which didn't know about the case bits.

MTOOLS_NO_VFAT

If this is set to 1, mtools won't generate VFAT entries for filenames which are mixed-case, but otherwise legal dos filenames. This is useful when working with DOS versions which can't grok VFAT long names, such as FreeDOS.

MTOOLS_DOTTED_DIR

In a wide directory, prints the short name with a dot instead of spaces separating the basename and the extension.

MTOOLS_NAME_NUMERIC_TAIL

If this is set to one (default), generate numeric tails for all long names (~1). If set to zero, only generate numeric tails if otherwise a clash would have happened.

MTOOLS_TWENTY_FOUR_HOUR_CLOCK

If 1, uses the European notation for times (twenty four hour clock), else uses the UK/US notation (am/pm)

MTOOLS_LOCK_TIMEOUT

How long, in seconds, to wait for a locked device to become free. Defaults to 30.

Example: Inserting the following line into your configuration file instructs mtools to skip the sanity checks:

```
  MTOOLS_SKIP_CHECK=1
```

Global variables may also be set via the environment:

```
  export MTOOLS_SKIP_CHECK=1
```

Global string variables may be set to any value:

MTOOLS_DATE_STRING

The format used for printing dates of files. By default, is dd-mm-yyyy.

###  General information
Per drive flags and values may be described in a drive section. A drive section starts with drive "driveletter" :

Then follow variable-value pairs and flags.

This is a sample drive description:

```
  drive a:

    file="/dev/fd0" use_xdf=1
```

###  Location information
For each drive, you need to describe where its data is physically stored (image file, physical device, partition, offset).

file

The name of the file or device holding the disk image. This is mandatory. The file name should be enclosed in quotes.

partition

Tells mtools to treat the drive as a partitioned device, and to use the given partition. Only primary partitions are accessible using this method, and they are numbered from 1 to 4. For logical partitions, use the more general offset variable. The partition variable is intended for removable media such as Syquest disks, ZIP drives, and magneto-optical disks. Although traditional DOS sees Syquest disks and magneto-optical disks as `giant floppy disks' which are unpartitioned, OS/2 and Windows NT treat them like hard disks, i.e. partitioned devices. The partition flag is also useful DOSEMU hdimages. It is not recommended for hard disks for which direct access to partitions is available through mounting.

offset

Describes where in the file the MS-DOS file system starts. This is useful for logical partitions in DOSEMU hdimages, and for ATARI ram disks. By default, this is zero, meaning that the file system starts right at the beginning of the device or file.

###  Disk Geometry Configuration
Geometry information describes the physical characteristics about the disk. Its has three purposes:

formatting

The geometry information is written into the boot sector of the newly made disk. However, you may also describe the geometry information on the command line. See section mformat, for details.

filtering

On some Unixes there are device nodes which only support one physical geometry. For instance, you might need a different node to access a disk as high density or as low density. The geometry is compared to the actual geometry stored on the boot sector to make sure that this device node is able to correctly read the disk. If the geometry doesn't match, this drive entry fails, and the next drive entry bearing the same drive letter is tried. See section multiple descriptions, for more details on supplying several descriptions for one drive letter.

If no geometry information is supplied in the configuration file, all disks are accepted. On Linux (and on SPARC) there exist device nodes with configurable geometry (`/dev/fd0', `/dev/fd1' etc), and thus filtering is not needed (and ignored) for disk drives. (Mtools still does do filtering on plain files (disk images) in Linux: this is mainly intended for test purposes, as I don't have access to a Unix which would actually need filtering).

If you do not need filtering, but want still a default geometry for mformatting, you may switch off filtering using the mformat_only flag.

If you want filtering, you should supply the filter flag. If you supply a geometry, you must supply one of both flags.

initial geometry

On devices that support it (usually floppy devices), the geometry information is also used to set the initial geometry. This initial geometry is applied while reading the boot sector, which contains the real geometry. If no geometry information is supplied in the configuration file, or if the mformat_only flag is supplied, no initial configuration is done.

On Linux, initial geometry is not really needed, as the configurable devices are able to auto-detect the disk type accurately enough (for most common formats) to read the boot sector.

Wrong geometry information may lead to very bizarre errors. That's why I strongly recommend that you add the mformat_only flag to your drive description, unless you really need filtering or initial geometry.

The following geometry related variables are available:

cylinders

tracks

The number of cylinders. (cylinders is the preferred form, tracks is considered obsolete)

heads

The number of heads (sides).

sectors

The number of sectors per track.

Example: the following drive section describes a 1.44M drive:

```
  drive a:

      file="/dev/fd0H1440"

      fat_bits=12

      cylinders=80 heads=2 sectors=18

      mformat_only
```

The following shorthand geometry descriptions are available:

1.44m

high density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80 heads=2 sectors=18

1.2m

high density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=80 heads=2 sectors=15

720k

double density 3 1/2 disk. Equivalent to: fat_bits=12 cylinders=80 heads=2 sectors=9

360k

double density 5 1/4 disk. Equivalent to: fat_bits=12 cylinders=40 heads=2 sectors=9

The shorthand format descriptions may be amended. For example, 360k sectors=8 describes a 320k disk and is equivalent to: fat_bits=12 cylinders=40 heads=2 sectors=8

###  Open Flags
Moreover, the following flags are available:

sync

All i/o operations are done synchronously

nodelay

The device or file is opened with the O_NDELAY flag. This is needed on some non-Linux architectures.

exclusive

The device or file is opened with the O_EXCL flag. On Linux, this ensures exclusive access to the floppy drive. On most other architectures, and for plain files it has no effect at all.

###  General Purpose Drive Variables
The following general purpose drive variables are available. Depending to their type, these variables can be set to a string (precmd, postcmd) or an integer (all others)

fat_bits

The number of FAT bits. This may be 12 or 16. This is very rarely needed, as it can almost always be deduced from information in the boot sector. On the contrary, describing the number of fat bits may actually be harmful if you get it wrong. You should only use it if mtools gets the auto-detected number of fat bits wrong, or if you want to mformat a disk with a weird number of fat bits.

codepage

Describes the DOS code page used for short filenames. This is a number between 1 and 999. By default, code page 850 is used. The reason for this is because this code page contains most of the characters that are also available in ISO-Latin-1. You may also specify a global code page for all drives by using the global default_codepage parameter (outside of any drive description). This parameters exists starting at version 4.0.0

data_map

Remaps data from image file. This is useful for image files which might need additional zero-filled sectors to be inserted. Such is the case for instance for IBM 3174 floppy images. These images represent floppy disks with fewer sectors on their first cylinder. These missing sectors are not stored in the image, but are still counted in the filesystem layout. The data_map allows to fake these missing sectors for the upper layers of mtools. A data_map is a comma-separated sequence of source type and size. Source type may be zero for zero-filled sectors created by map, skip for data in raw image to be ignored (skipped), and nothing for data to be used as is (copied) from the raw image. Datamap is automatically complemented by an implicit last element of data to be used as is from current offset to end of file. Each size is a number followed by a unit: s for a 512 byte sector, K for Kbytes, M for megabytes, G for gigabytes, and nothing for single bytes.

Example:

data_map=1s,zero31s,28s,skip1s would be a map for use with IBM 3174 floppy images. First sector (1s, boot sector) is used as is. Then follow 31 fake zero-filled sectors (zero31s), then the next 28 sectors from image (28s) are used as is (they contain FAT and root directory), then one sector from image is skipped (skip1s), and finally the rest of image is used as is (implicit)

precmd

Executes the given command before opening the device. On some variants of Solaris, it is necessary to call 'volcheck -v' before opening a floppy device, in order for the system to notice that there is indeed a disk in the drive. precmd="volcheck -v" in the drive clause establishes the desired behavior.

postcmd

Executes the given command after closing the device. May be useful if mtools shares the image file with some other application, in order to release the image file to that application.

blocksize

This parameter represents a default block size to be always used on this device. All I/O is done with multiples of this block size, independently of the sector size registered in the file system's boot sector. This is useful for character devices whose sector size is not 512, such as for example CD-ROM drives on Solaris.

Only the file variable is mandatory. The other parameters may be left out. In that case a default value or an auto-detected value is used.

###  General Purpose Drive Flags
A flag can either be set to 1 (enabled) or 0 (disabled). If the value is omitted, it is enabled. For example, scsi is equivalent to scsi=1

nolock

Instruct mtools to not use locking on this drive. This is needed on systems with buggy locking semantics. However, enabling this makes operation less safe in cases where several users may access the same drive at the same time.

scsi

When set to 1, this option tells mtools to use raw SCSI I/O instead of the standard read/write calls to access the device. Currently, this is supported on HP-UX, Solaris and SunOS. This is needed because on some architectures, such as SunOS or Solaris, PC media can't be accessed using the read and write system calls, because the OS expects them to contain a Sun specific "disk label".

As raw SCSI access always uses the whole device, you need to specify the "partition" flag in addition

On some architectures, such as Solaris, mtools needs root privileges to be able to use the scsi option. Thus mtools should be installed setuid root on Solaris if you want to access Zip/Jaz drives. Thus, if the scsi flag is given, privileged is automatically implied, unless explicitly disabled by privileged=0

Mtools uses its root privileges to open the device, and to issue the actual SCSI I/O calls. Moreover, root privileges are only used for drives described in a system-wide configuration file such as `/etc/mtools.conf', and not for those described in `~/.mtoolsrc' or `$MTOOLSRC'.

privileged

When set to 1, this instructs mtools to use its setuid and setgid privileges for opening the given drive. This option is only valid for drives described in the system-wide configuration files (such as `/etc/mtools.conf', not `~/.mtoolsrc' or `$MTOOLSRC'). Obviously, this option is also a no op if mtools is not installed setuid or setgid. This option is implied by 'scsi=1', but again only for drives defined in system-wide configuration files. Privileged may also be set explicitly to 0, in order to tell mtools not to use its privileges for a given drive even if scsi=1 is set.

Mtools only needs to be installed setuid if you use the privileged or scsi drive variables. If you do not use these options, mtools works perfectly well even when not installed setuid root.

vold

Instructs mtools to interpret the device name as a vold identifier rather than as a filename. The vold identifier is translated into a real filename using the media_findname() and media_oldaliases() functions of the volmgt library. This flag is only available if you configured mtools with the --enable-new-vold option before compilation.

swap

Consider the media as a word-swapped Atari disk.

use_xdf

If this is set to a non-zero value, mtools also tries to access this disk as an XDF disk. XDF is a high capacity format used by OS/2. This is off by default. See section XDF, for more details.

mformat_only

Tells mtools to use the geometry for this drive only for mformatting and not for filtering.

filter

Tells mtools to use the geometry for this drive both for mformatting and filtering.

remote

Tells mtools to connect to floppyd (see section floppyd).

###  Supplying multiple descriptions for a drive
It is possible to supply multiple descriptions for a drive. In that case, the descriptions are tried in order until one is found that fits. Descriptions may fail for several reasons:

1.

because the geometry is not appropriate,

2.

because there is no disk in the drive,

3.

or because of other problems.

Multiple definitions are useful when using physical devices which are only able to support one single disk geometry. Example:

```
  drive a: file="/dev/fd0H1440" 1.44m

  drive a: file="/dev/fd0H720" 720k
```

This instructs mtools to use /dev/fd0H1440 for 1.44m (high density) disks and /dev/fd0H720 for 720k (double density) disks. On Linux, this feature is not really needed, as the /dev/fd0 device is able to handle any geometry.

You may also use multiple drive descriptions to access both of your physical drives through one drive letter:

```
  drive z: file="/dev/fd0"

  drive z: file="/dev/fd1"
```

With this description, mdir z: accesses your first physical drive if it contains a disk. If the first drive doesn't contain a disk, mtools checks the second drive.

When using multiple configuration files, drive descriptions in the files parsed last override descriptions for the same drive in earlier files. In order to avoid this, use the drive+ or +drive keywords instead of drive. The first adds a description to the end of the list (i.e. it will be tried last), and the first adds it to the start of the list.

### Location of configuration files and parsing order
The configuration files are parsed in the following order:

1.

compiled-in defaults

2.

`/etc/mtools.conf'

3.

`~/.mtoolsrc'.

4.

`$MTOOLSRC' (file pointed by the MTOOLSRC environmental variable)

Options described in the later files override those described in the earlier files. Drives defined in earlier files persist if they are not overridden in the later files. For instance, drives A and B may be defined in `/etc/mtools.conf' and drives C and D may be defined in `~/.mtoolsrc' However, if `~/.mtoolsrc' also defines drive A, this new description would override the description of drive A in `/etc/mtools.conf' instead of adding to it. If you want to add a new description to a drive already described in an earlier file, you need to use either the +drive or drive+ keyword.

### Backwards compatibility with old configuration file syntax
The syntax described herein is new for version mtools-3.0. The old line-oriented syntax is still supported. Each line beginning with a single letter is considered to be a drive description using the old syntax. Old style and new style drive sections may be mixed within the same configuration file, in order to make upgrading easier. Support for the old syntax will be phased out eventually, and in order to discourage its use, I purposefully omit its description here.

## See also
mtools


mu-bookmarks

package: mu

title: mu-bookmarks(5)

text:
# mu-bookmarks(5)

## NAME
bookmarks - file with bookmarks (shortcuts) for mu search expressions

## DESCRIPTION
Bookmarks are named shortcuts for search queries. They allow using a convenient name for often-used queries. The bookmarks are also visible as shortcuts in the mu experimental user interfaces, mug and mug2.

The bookmarks file is read from <muhome>/bookmarks. On Unix this would typically be w be ~/.config/mu/bookmarks, but this can be influenced using the --muhome parameter for mu-find(1).

The bookmarks file is a typical key=value .ini-file, which is best shown by means of an example:

```
[mu]
inbox=maildir:/inbox                  # inbox
oldhat=maildir:/archive subject:hat   # archived with subject containing 'hat'
```

The [mu] group header is required. For practical uses of bookmarks, see mu-find(1).

## AUTHOR
Dirk-Jan C. Binnema <djcb@djcbsoftware.nl>

## COPYRIGHT
This manpage is part of mu 1.10.7.

Copyright © 2022-2023 Dirk-Jan C. Binnema. License GPLv3+: GNU GPL version 3 or later https://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.

## SEE ALSO
mu(1), mu-find(1)