title: zmq_gssapi(7)

text:
# zmq_gssapi(7)

## NAME
zmq_gssapi - secure authentication and confidentiality

## SYNOPSIS
The GSSAPI mechanism defines a mechanism for secure authentication and confidentiality for communications between a client and a server using the Generic Security Service Application Program Interface (GSSAPI). The GSSAPI mechanism can be used on both public and private networks. GSSAPI itself is defined in IETF RFC-2743: http://tools.ietf.org/html/rfc2743. The ZeroMQ GSSAPI mechanism is defined by this document: http://rfc.zeromq.org/spec:38.

## CLIENT AND SERVER ROLES
A socket using GSSAPI can be either client or server, but not both.

To become a GSSAPI server, the application sets the ZMQ_GSSAPI_SERVER option on the socket.

To become a GSSAPI client, the application sets the ZMQ_GSSAPI_SERVICE_PRINCIPAL option to the name of the principal on the server to which it intends to connect.

On client or server, the application may additionally set the ZMQ_GSSAPI_PRINCIPAL option to provide the socket with the name of the principal for whom GSSAPI credentials should be acquired. If this option is not set, default credentials are used.

## OPTIONAL ENCRYPTION
By default, the GSSAPI mechanism will encrypt all communications between client and server. If encryption is not desired (e.g. on private networks), the client and server applications can disable it by setting the ZMQ_GSSAPI_PLAINTEXT option. Both the client and server must set this option to the same value.

## PRINCIPAL NAMES
Principal names specified with the ZMQ_GSSAPI_SERVICE_PRINCIPAL or ZMQ_GSSAPI_PRINCIPAL options are interpreted as "host based" name types by default. The ZMQ_GSSAPI_PRINCIPAL_NAMETYPE and ZMQ_GSSAPI_SERVICE_PRINCIPAL_NAMETYPE options may be used to change the name type to one of:

ZMQ_GSSAPI_NT_HOSTBASED

The name should be of the form "service" or "service@hostname", which will parse into a principal of "service/hostname" in the local realm. This is the default name type.

ZMQ_GSSAPI_NT_USER_NAME

The name should be a local username, which will parse into a single-component principal in the local realm.

ZMQ_GSSAPI_NT_KRB5_PRINCIPAL

The name is a principal name string. This name type only works with the krb5 GSSAPI mechanism.

## SEE ALSO
zmq_setsockopt(3) zmq_null(7) zmq_curve(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


package: libzeromq-devel

title: zmq_inproc(7)

summary: 0MQ local in\-process (inter\-thread) communication transport

text:
# zmq_inproc(7)

## NAME
zmq_inproc - 0MQ local in-process (inter-thread) communication transport

## SYNOPSIS
The in-process transport passes messages via memory directly between threads sharing a single 0MQ context.

Note No I/O threads are involved in passing messages using the inproc transport. Therefore, if you are using a 0MQ context for in-process messaging only you can initialise the context with zero I/O threads. See zmq_init(3) for details.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the in-process transport, the transport is inproc, and the meaning of the address part is defined below.

### Assigning a local address to a socket
When assigning a local address to a socket using zmq_bind() with the inproc transport, the endpoint shall be interpreted as an arbitrary string identifying the name to create. The name must be unique within the 0MQ context associated with the socket and may be up to 256 characters in length. No other restrictions are placed on the format of the name.

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the inproc transport, the endpoint shall be interpreted as an arbitrary string identifying the name to connect to. Before version 4.0 he name must have been previously created by assigning it to at least one socket within the same 0MQ context as the socket being connected. Since version 4.0 the order of zmq_bind() and zmq_connect() does not matter just like for the tcp transport type.

## EXAMPLES
Assigning a local address to a socket.

```
//  Assign the in-process name "#1"
rc = zmq_bind(socket, "inproc://#1");
assert (rc == 0);
//  Assign the in-process name "my-endpoint"
rc = zmq_bind(socket, "inproc://my-endpoint");
assert (rc == 0);
```

Connecting a socket.

```
//  Connect to the in-process name "#1"
rc = zmq_connect(socket, "inproc://#1");
assert (rc == 0);
//  Connect to the in-process name "my-endpoint"
rc = zmq_connect(socket, "inproc://my-endpoint");
assert (rc == 0);
```

## SEE ALSO
zmq_bind(3) zmq_connect(3) zmq_ipc(7) zmq_tcp(7) zmq_pgm(7) zmq_vmci(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_ipc(7)

summary: 0MQ local inter\-process communication transport

text:
# zmq_ipc(7)

## NAME
zmq_ipc - 0MQ local inter-process communication transport

## SYNOPSIS
The inter-process transport passes messages between local processes using a system-dependent IPC mechanism.

Note The inter-process transport is currently only implemented on operating systems that provide UNIX domain sockets.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the inter-process transport, the transport is ipc, and the meaning of the address part is defined below.

### Binding a socket
When binding a socket to a local address using zmq_bind() with the ipc transport, the endpoint shall be interpreted as an arbitrary string identifying the pathname to create. The pathname must be unique within the operating system namespace used by the ipc implementation, and must fulfill any restrictions placed by the operating system on the format and length of a pathname.

When the address is wild-card *, zmq_bind() shall generate a unique temporary pathname. The caller should retrieve this pathname using the ZMQ_LAST_ENDPOINT socket option. See zmq_getsockopt(3) for details.

Note any existing binding to the same endpoint shall be overridden. That is, if a second process binds to an endpoint already bound by a process, this will succeed and the first process will lose its binding. In this behaviour, the ipc transport is not consistent with the tcp or inproc transports.

Note the endpoint pathname must be writable by the process. When the endpoint starts with /, e.g., ipc:///pathname, this will be an absolute pathname. If the endpoint specifies a directory that does not exist, the bind shall fail.

Note on Linux only, when the endpoint pathname starts with @, the abstract namespace shall be used. The abstract namespace is independent of the filesystem and if a process attempts to bind an endpoint already bound by a process, it will fail. See unix(7) for details.

Note IPC pathnames have a maximum size that depends on the operating system. On Linux, the maximum is 113 characters including the "ipc://" prefix (107 characters for the real path name).

### Unbinding wild-card address from a socket
When wild-card * endpoint was used in zmq_bind(), the caller should use real endpoint obtained from the ZMQ_LAST_ENDPOINT socket option to unbind this endpoint from a socket using zmq_unbind().

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the ipc transport, the endpoint shall be interpreted as an arbitrary string identifying the pathname to connect to. The pathname must have been previously created within the operating system namespace by assigning it to a socket with zmq_bind().

## EXAMPLES
Assigning a local address to a socket.

```
//  Assign the pathname "/tmp/feeds/0"
rc = zmq_bind(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
```

Connecting a socket.

```
//  Connect to the pathname "/tmp/feeds/0"
rc = zmq_connect(socket, "ipc:///tmp/feeds/0");
assert (rc == 0);
```

## SEE ALSO
zmq_bind(3) zmq_connect(3) zmq_inproc(7) zmq_tcp(7) zmq_pgm(7) zmq_vmci(7) zmq_getsockopt(3) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_null(7)

summary: no security or confidentiality

text:
# zmq_null(7)

## NAME
zmq_null - no security or confidentiality

## SYNOPSIS
The NULL mechanism is defined by the ZMTP 3.0 specification: http://rfc.zeromq.org/spec:23. This is the default security mechanism for ZeroMQ sockets.

## SEE ALSO
zmq_plain(7) zmq_curve(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_pgm(7)

text:
# zmq_pgm(7)

## NAME
zmq_pgm - 0MQ reliable multicast transport using PGM

## SYNOPSIS
PGM (Pragmatic General Multicast) is a protocol for reliable multicast transport of data over IP networks.

## DESCRIPTION
0MQ implements two variants of PGM, the standard protocol where PGM datagrams are layered directly on top of IP datagrams as defined by RFC 3208 (the pgm transport) and "Encapsulated PGM" or EPGM where PGM datagrams are encapsulated inside UDP datagrams (the epgm transport).

The pgm and epgm transports can only be used with the ZMQ_PUB and ZMQ_SUB socket types.

Further, PGM sockets are rate limited by default. For details, refer to the ZMQ_RATE, and ZMQ_RECOVERY_IVL options documented in zmq_setsockopt(3).

Caution The pgm transport implementation requires access to raw IP sockets. Additional privileges may be required on some operating systems for this operation. Applications not requiring direct interoperability with other PGM implementations are encouraged to use the epgm transport instead which does not require any special privileges.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the PGM transport, the transport is pgm, and for the EPGM protocol the transport is epgm. The meaning of the address part is defined below.

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the pgm or epgm transport, the endpoint shall be interpreted as an interface followed by a semicolon, followed by a multicast address, followed by a colon and a port number.

An interface may be specified by either of the following:

•The interface name as defined by the operating system.

•The primary IPv4 address assigned to the interface, in its numeric representation.

Note Interface names are not standardised in any way and should be assumed to be arbitrary and platform dependent. On Win32 platforms no short interface names exist, thus only the primary IPv4 address may be used to specify an interface. The interface part can be omitted, in that case the default one will be selected.

A multicast address is specified by an IPv4 multicast address in its numeric representation.

## WIRE FORMAT
Consecutive PGM datagrams are interpreted by 0MQ as a single continuous stream of data where 0MQ messages are not necessarily aligned with PGM datagram boundaries and a single 0MQ message may span several PGM datagrams. This stream of data consists of 0MQ messages encapsulated in frames as described in zmq_tcp(7).

### PGM datagram payload
The following ABNF grammar represents the payload of a single PGM datagram as used by 0MQ:

```
datagram               = (offset data)
offset                 = 2OCTET
data                   = *OCTET
```

In order for late joining consumers to be able to identify message boundaries, each PGM datagram payload starts with a 16-bit unsigned integer in network byte order specifying either the offset of the first message frame in the datagram or containing the value 0xFFFF if the datagram contains solely an intermediate part of a larger message.

Note that offset specifies where the first message begins rather than the first message part. Thus, if there are trailing message parts at the beginning of the packet the offset ignores them and points to first initial message part in the packet.

The following diagram illustrates the layout of a single PGM datagram payload:

```
+------------------+----------------------+
| offset (16 bits) |         data         |
+------------------+----------------------+
```

The following diagram further illustrates how three example 0MQ frames are laid out in consecutive PGM datagram payloads:

```
First datagram payload
+--------------+-------------+---------------------+
| Frame offset |   Frame 1   |   Frame 2, part 1   |
|    0x0000    | (Message 1) | (Message 2, part 1) |
+--------------+-------------+---------------------+
Second datagram payload
+--------------+---------------------+
| Frame offset |   Frame 2, part 2   |
| 0xFFFF       | (Message 2, part 2) |
+--------------+---------------------+
Third datagram payload
+--------------+----------------------------+-------------+
| Frame offset |   Frame 2, final 8 bytes   |   Frame 3   |
| 0x0008       | (Message 2, final 8 bytes) | (Message 3) |
+--------------+----------------------------+-------------+
```

## EXAMPLE
Connecting a socket.

```
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the first Ethernet network interface on Linux
//  and the Encapsulated PGM protocol
rc = zmq_connect(socket, "epgm://eth0;239.192.1.1:5555");
assert (rc == 0);
//  Connecting to the multicast address 239.192.1.1, port 5555,
//  using the network interface with the address 192.168.1.1
//  and the standard PGM protocol
rc = zmq_connect(socket, "pgm://192.168.1.1;239.192.1.1:5555");
assert (rc == 0);
```

## SEE ALSO
zmq_connect(3) zmq_setsockopt(3) zmq_tcp(7) zmq_ipc(7) zmq_inproc(7) zmq_vmci(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_plain(7)

summary: clear\-text authentication

text:
# zmq_plain(7)

## NAME
zmq_plain - clear-text authentication

## SYNOPSIS
The PLAIN mechanism defines a simple username/password mechanism that lets a server authenticate a client. PLAIN makes no attempt at security or confidentiality. It is intended for use on internal networks where security requirements are low. The PLAIN mechanism is defined by this document: http://rfc.zeromq.org/spec:24.

## USAGE
To use PLAIN, the server shall set the ZMQ_PLAIN_SERVER option, and the client shall set the ZMQ_PLAIN_USERNAME and ZMQ_PLAIN_PASSWORD socket options. Which peer binds, and which connects, is not relevant.

## SEE ALSO
zmq_setsockopt(3) zmq_null(7) zmq_curve(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_tcp(7)

summary: 0MQ unicast transport using TCP

text:
# zmq_tcp(7)

## NAME
zmq_tcp - 0MQ unicast transport using TCP

## SYNOPSIS
TCP is an ubiquitous, reliable, unicast transport. When connecting distributed applications over a network with 0MQ, using the TCP transport will likely be your first choice.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the TCP transport, the transport is tcp, and the meaning of the address part is defined below.

### Assigning a local address to a socket
When assigning a local address to a socket using zmq_bind() with the tcp transport, the endpoint shall be interpreted as an interface followed by a colon and the TCP port number to use.

An interface may be specified by either of the following:

•The wild-card *, meaning all available interfaces.

•The primary IPv4 or IPv6 address assigned to the interface, in its numeric representation.

•The non-portable interface name as defined by the operating system.

The TCP port number may be specified by:

•A numeric value, usually above 1024 on POSIX systems.

•The wild-card *, meaning a system-assigned ephemeral port.

When using ephemeral ports, the caller should retrieve the actual assigned port using the ZMQ_LAST_ENDPOINT socket option. See zmq_getsockopt(3) for details.

### Unbinding wild-card address from a socket
When wild-card * endpoint was used in zmq_bind(), the caller should use real endpoint obtained from the ZMQ_LAST_ENDPOINT socket option to unbind this endpoint from a socket using zmq_unbind().

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the tcp transport, the endpoint shall be interpreted as a peer address followed by a colon and the TCP port number to use. You can optionally specify a source_endpoint which will be used as the source address for your connection; tcp://source_endpoint;'endpoint', see the interface description above for details.

A peer address may be specified by either of the following:

•The DNS name of the peer.

•The IPv4 or IPv6 address of the peer, in its numeric representation.

Note: A description of the ZeroMQ Message Transport Protocol (ZMTP) which is used by the TCP transport can be found at http://rfc.zeromq.org/spec:15

## EXAMPLES
Assigning a local address to a socket.

```
//  TCP port 5555 on all available interfaces
rc = zmq_bind(socket, "tcp://*:5555");
assert (rc == 0);
//  TCP port 5555 on the local loop-back interface on all platforms
rc = zmq_bind(socket, "tcp://127.0.0.1:5555");
assert (rc == 0);
//  TCP port 5555 on the first Ethernet network interface on Linux
rc = zmq_bind(socket, "tcp://eth0:5555");
assert (rc == 0);
```

Connecting a socket.

```
//  Connecting using an IP address
rc = zmq_connect(socket, "tcp://192.168.1.1:5555");
assert (rc == 0);
//  Connecting using a DNS name
rc = zmq_connect(socket, "tcp://server1:5555");
assert (rc == 0);
//  Connecting using a DNS name and bind to eth1
rc = zmq_connect(socket, "tcp://eth1:0;server1:5555");
assert (rc == 0);
//  Connecting using a IP address and bind to an IP address
rc = zmq_connect(socket, "tcp://192.168.1.17:5555;192.168.1.1:5555");
assert (rc == 0);
```

## SEE ALSO
zmq_bind(3) zmq_connect(3) zmq_pgm(7) zmq_ipc(7) zmq_inproc(7) zmq_vmci(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_tipc(7)

summary: 0MQ unicast transport using TIPC

text:
# zmq_tipc(7)

## NAME
zmq_tipc - 0MQ unicast transport using TIPC

## SYNOPSIS
TIPC is a cluster IPC protocol with a location transparent addressing scheme.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the TIPC transport, the transport is tipc, and the meaning of the address part is defined below.

### Assigning a port name to a socket
When assigning a port name to a socket using zmq_bind() with the tipc transport, the endpoint is defined in the form: {type, lower, upper}

•Type is the numerical (u32) ID of your service.

•Lower and Upper specify a range for your service.

Publishing the same service with overlapping lower/upper ID’s will cause connection requests to be distributed over these in a round-robin manner.

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the tipc transport, the endpoint shall be interpreted as a service ID, followed by a comma and the instance ID.

The instance ID must be within the lower/upper range of a published port name for the endpoint to be valid.

## EXAMPLES
Assigning a local address to a socket.

```
//  Publish TIPC service ID 5555
rc = zmq_bind(socket, "tipc://{5555,0,0}");
assert (rc == 0);
//  Publish TIPC service ID 5555 with a service range of 0-100
rc = zmq_bind(socket, "tipc://{5555,0,100}");
assert (rc == 0);
```

Connecting a socket.

```
//  Connect to service 5555 instance id 50
rc = zmq_connect(socket, "tipc://{5555,50}");
assert (rc == 0);
```

## SEE ALSO
zmq_bind(3) zmq_connect(3) zmq_tcp(7) zmq_pgm(7) zmq_ipc(7) zmq_inproc(7) zmq_vmci(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_udp(7)

summary: 0MQ UDP multicast and unicast transport

text:
# zmq_udp(7)

## NAME
zmq_udp - 0MQ UDP multicast and unicast transport

## SYNOPSIS
UDP is unreliable protocol transport of data over IP networks. UDP support both unicast and multicast communication.

## DESCRIPTION
UDP transport can only be used with the ZMQ_RADIO and ZMQ_DISH socket types.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the UDP transport, the transport is udp. The meaning of the address part is defined below.

Binding a socket

```
With 'udp' we can only bind the 'ZMQ_DISH' socket type.
When binding a socket using _zmq_bind()_ with the 'udp'
transport the 'endpoint' shall be interpreted as an 'interface' followed by a
colon and the UDP port number to use.
An 'interface' may be specified by either of the following:
* The wild-card `*`, meaning all available interfaces.
* The primary IPv4 address assigned to the interface, in its numeric

  representation.
* Multicast address in its numeric representation the socket should join.
The UDP port number may be specified a numeric value, usually above 1024 on POSIX systems.
Connecting a socket
```

With udp we can only connect the ZMQ_RADIO socket type. When connecting a socket to a peer address using zmq_connect() with the udp transport, the endpoint shall be interpreted as a peer address followed by a colon and the UDP port number to use.

A peer address may be specified by either of the following:

•The IPv4 or IPv6 address of the peer, in its numeric representation.

•Multicast address in its numeric representation.

## EXAMPLES
Binding a socket.

```
//  Unicast - UDP port 5555 on all available interfaces
rc = zmq_bind(dish, "udp://*:5555");
assert (rc == 0);
//  Unicast - UDP port 5555 on the local loop-back interface
rc = zmq_bind(dish, "udp://127.0.0.1:5555");
assert (rc == 0);
//  Multicast - UDP port 5555 on a Multicast address
rc = zmq_bind(dish, "udp://239.0.0.1:5555");
assert (rc == 0);
```

Connecting a socket.

```
//  Connecting using an Unicast IP address
rc = zmq_connect(radio, "udp://192.168.1.1:5555");
assert (rc == 0);
//  Connecting using a Multicast address"
rc = zmq_connect(socket, "udp://239.0.0.1:5555);
assert (rc == 0);
```

## SEE ALSO
zmq_connect(3) zmq_setsockopt(3) zmq_tcp(7) zmq_ipc(7) zmq_inproc(7) zmq_vmci(7) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


title: zmq_vmci(7)

text:
# zmq_vmci(7)

## NAME
zmq_vmci - 0MQ transport over virtual machine communicatios interface (VMCI) sockets

## SYNOPSIS
The VMCI transport passes messages between VMware virtual machines running on the same host, between virtual machine and the host and within virtual machines (inter-process transport like ipc).

Note Communication between a virtual machine and the host is not supported on Mac OS X 10.9 and above.

## ADDRESSING
A 0MQ endpoint is a string consisting of a transport:// followed by an address. The transport specifies the underlying protocol to use. The address specifies the transport-specific address to connect to.

For the VMCI transport, the transport is vmci, and the meaning of the address part is defined below.

### Binding a socket
When binding a socket to a local address using zmq_bind() with the vmci transport, the endpoint shall be interpreted as an interface followed by a colon and the TCP port number to use.

An interface may be specified by either of the following:

•The wild-card *, meaning all available interfaces.

•An integer returned by VMCISock_GetLocalCID or @ (ZeroMQ will call VMCISock_GetLocalCID internally).

The port may be specified by:

•A numeric value, usually above 1024 on POSIX systems.

•The wild-card *, meaning a system-assigned ephemeral port.

### Unbinding wild-card address from a socket
When wild-card * endpoint was used in zmq_bind(), the caller should use real endpoint obtained from the ZMQ_LAST_ENDPOINT socket option to unbind this endpoint from a socket using zmq_unbind().

### Connecting a socket
When connecting a socket to a peer address using zmq_connect() with the vmci transport, the endpoint shall be interpreted as a peer address followed by a colon and the port number to use.

A peer address must be a CID of the peer.

## EXAMPLES
Assigning a local address to a socket.

```
//  VMCI port 5555 on all available interfaces
rc = zmq_bind(socket, "vmci://*:5555");
assert (rc == 0);
//  VMCI port 5555 on the local loop-back interface on all platforms
cid = VMCISock_GetLocalCID();
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_bind(socket, endpoint);
assert (rc == 0);
```

Connecting a socket.

```
//  Connecting using a CID
sprintf(endpoint, "vmci://%d:5555", cid);
rc = zmq_connect(socket, endpoint);
assert (rc == 0);
```

## SEE ALSO
zmq_bind(3) zmq_connect(3) zmq_inproc(7) zmq_tcp(7) zmq_pgm(7) zmq_vmci(7) zmq_getsockopt(3) zmq(7)

## AUTHORS
This page was written by the 0MQ community. To make a change please read the 0MQ Contribution Policy at http://www.zeromq.org/docs:contributing.


qos

package: linux-atm

title: qos(7)

summary: Quality of Service specification

text:
# qos(7)

## NAME
qos - Quality of Service specification

## DESCRIPTION
The text2qos and qos2text functions use the format described in this man page. Because all standard ATM tools on Linux use those functions to convert to or from the textual representation of QOS specifications, they expect them in the same format too.

The most fundamental parameters are the traffic class and the AAL (ATM Adaption Layer) type. If the connection is bi-directional, both directions have the same traffic class and the same AAL type. The traffic class and the AAL type are the first elements (in any order) in a QOS specification. The traffic class is the only required element. If the AAL type is omitted, the application will provide a default value. The following traffic classes are recognized:

ubr

Unassigned Bit Rate

cbr

Constant Bit Rate

abr

Available Bit Rate

The following AAL types are recognized:

aal0

("raw ATM")

aal5

If both, the traffic class and the AAL type are specified, they are separated by a comma.

If more parameters are supplied, the traffic class and AAL type must be followed by a colon. Traffic parameters can be specified independently for the transmit and the receive direction. Their parameter lists are prefixed with tx: and rx:, respectively. If both parameter lists are present, the tx: list must precede the rx: list. If a parameter is equal for both directions, it can be placed in a common parameter list (without prefix). The general format is as follows:

class_and_aal:common_list,tx:list,rx:list

Each list consists of elements specifying a parameter. Elements can appear in any order and they are separated with commas. The following elements are recognized:

pcr=rate

is a synonym for max_pcr=rate

max_pcr=rate

The upper limit for the peak cell rate to assign. If omitted, any rate up to link speed may be chosen.

min_pcr=rate

The lower limit for the peak cell rate to assign. If omitted, any rate above zero can be chosen.

sdu=size

is a synonym for max_sdu=size

max_sdu=size

The size of the largest packet that may be sent or received. If omitted, a context-dependent default value is used.

Values are specified as follows:

rate

The (decimal) rate, optionally followed by a unit. The unit may be prefixed with one of the multipliers k, M, or G, meaning 1'000, 1'000'000, or 1'000'000'000, respectively. The units cps (cells per second) and bps (bits per second) are recognized. If multiplier and unit are omitted, cells per second are assumed. Note that the rate is always converted to cells per second, so rounding errors may occur when specifying the rate in bits per second. Rates measured in bits per second are considered to be user data rates, i.e. one cell corresponds to 384 bits. The rate can be a fractional value, e.g. 1.3Mbps. It is an error to specify only a multiplier without a unit. Link speed can be indicated by using the keyword max as the rate.

size

The (decimal) number of bytes.

The tx: or rx: lists may also just contain the single element none, which indicates that the corresponding direction is not used. It is an error to specify none for both direction.

Note that commas must never follow colons or other commas. Also, whitespace is not allowed inside a QOS specification. QOS specifications are case-insensitive.

## EXAMPLES
Each of the following lines contains a valid QOS specification:

```
  ubr

  ubr:pcr=100kbps

  cbr,aal0:pcr=64kbps

  CBR:max_pcr=11Mbps,min_pcr=10mbps,sdu=8192

  aal5,ubr:tx:none

  cbr:tx:pcr=30000,rx:none
```

The following specificiations are equivalent:

```
  CBR,AAL5:PCR=48Mbps

  cbr,aal5:max_pcr=125000

  cbr,aal5:tx:pcr=125kcps,rx:pcr=125kcps
```

## AUTHOR
Werner Almesberger, EPFL LRC/ICA <werner.almesberger@epfl.ch>


sap

title: sap(7)

summary: Service Access Point specification

text:
# sap(7)

## NAME
sap - Service Access Point specification

## DESCRIPTION
The text2sap and sap2text functions use the format described in this man page. Because all standard ATM tools on Linux use those functions to convert to or from the textual representation of SAP specifications, they expect them in the same format too.

The SAP is divided into two parts: the broadband high layer information (BHLI) and the broadband low layer information (BLLI). A SAP can contain one, both, or none of them. In the latter case, the SAP is usually considered as a wildcard SAP, i.e. a SAP that is compatible with any other SAP.

Each part begins with its name (bhli or blli), followed by a colon and a (non-empty) list of attributes, which are of the form attribute=value. Some attributes have sub-attributes, which follow them. Everything that isn't separated by a colon or an equal sign is separated by a comma.

Values which are a number of bytes are specified as the corresponding sequence of pairs of hex digits. The sequence can be optionally prefixed with 0x. Values with are integers in a given range can be specified in decimal (no prefix), octal (0 prefix), and hexadecimal (0x prefix).

The following, mutually exclusive attributes are allowed in the bhli part (see the corresponding ATM Forum and ITU documents for the semantics):

iso=1-8 bytes

ISO

user=1-8 bytes

User-specific

hlp=4 bytes

High layer profile. Note that this attribute only exists on UNI 3.0. text2sap only recognizes it if your system is configured to accept UNI 3.0 message formats.

oui=3 bytes,id=4 bytes

Vendor-specific application identifier

The structure of the bhli part is more complex. It distinguishes three layers, l1, l2, and l3, of which the first one is presently unsupported. For layer two, the following (mutually exclusive) possibilities exist:

l2=iso1745

Basic mode ISO 1745

l2=q291

ITU-T Q.291 (Rec. I.441)

l2=lapb

Extended LAPB, half-duplex (Rec. T.71)

l2=iso8802

LAN LLC (ISO/IEC 8802/2)

l2=x75

ITU-T X.75, SLP

l2=x25_ll ...

ITU-T X.25, link layer. This attribute and the following attributes through l2=iso7776 can optionally be followed by one or more of the following sub-attributes: mode=mode (mode of operation, either norm or ext), and window=window size (window size in k, 1-127).

l2=x25_ml ...

ITU-T X.25, multilink

l2=hdlc_arm ...

HDLC ARM (ISO/IEC 4335)

l2=hdlc_nrm ...

HDLC NRM (ISO/IEC 4335)

l2=hdlc_abm ...

HDLC ABM (ISO/IEC 4335)

l2=q992 ...

ITU-T Q.922

l2=iso7776 ...

ISO 7776 DTE-DTE

l2=user,info=information

User-specified. information is an integer in the range 0 to 255.

For layer three, the following (again, mutually exclusive) possibilities exist:

l3=iso8473

ITU-T X.233 | ISO/IEC 8473

l3=t70

ITU-T T.70 minimum network layer

l3=h321

ITU-T Recommendation H.321

l3=x25 ...

ITU-T X.25, packet layer. This attribute and the following attributes through l3=x223 can optionally be followed by one or more of the following sub-attributes: mode=mode (see above), size=default packet size (4-12, corresponding to 16-4096), window=window size (see above).

l3=iso8208 ...

ISO/IEC 8208

l3=x223 ...

ITU-T X.223 | ISO/IEC 8878

l3=tr9577,ipi=identifier ...

ISO/IEC TR 9577. identifier is the initial protocol identifier in the range 0-255. For SNAP (0x80), the keyword snap can be used, and the following sub-attributes have to be specified: oui=3 bytes, and pid=2 bytes.

l2=user,info=information

User-specified, see above.

l3=h310 ...

ITU-T Recommendation H.310. The sub-attribute term=type (terminal type, rx, tx, or rxtx) is recognized. If present, it enables the two additional sub-attributes fw_mpx=capability (forward multiplexing capability, ts, ts_fec, ps, ps_fec, or h221) and bw_mpx=capability. Both are optional.

Note that commas must never follow colons or other commas. Also, whitespace is not allowed inside a SAP specification. SAP specifications are case-insensitive. On input, items must be written in exactly the order used in this document.

## EXAMPLES
blli:l2=iso8802

Classical IP over ATM (RFC1577)

bhli:oui=0x0060D7,id=0x01000001,blli:l2=iso8802

Arequipa (RFC2170)

blli:l3=tr9577,ipi=snap,oui=0x00A03E,pid=0x0002

LAN Emulation

## AUTHOR
Werner Almesberger, EPFL LRC <werner.almesberger@lrc.di.epfl.ch>


lvmautoactivation

title: lvmautoactivation(7)

summary: LVM autoactivation

text:
# lvmautoactivation(7)

## NAME
lvmautoactivation — LVM autoactivation

## DESCRIPTION
Autoactivation is the activation of LVs performed automatically by the system in response to LVM devices being attached to the machine. When all PVs in a VG have been attached, the VG is complete, and LVs in the VG are activated.

Autoactivation of VGs, or specific LVs, can be prevented using vgchange or lvchange --setautoactivation n. The lvm.conf auto_activation_volume_list is another way to limit autoactivation.

### event autoactivation
LVM autoactivation is "event based", in which complete VGs are activated in response to uevents which occur during system startup or at any time after the system has started. An old form of autoactivation was "static" in which complete VGs are activated at a fixed point during system startup by a systemd service, and not in response to events.

Event based autoactivation is driven by udev, udev rules, and systemd. When a device is attached to a machine, a uevent is generated by the kernel to notify userspace of the new device. systemd-udev runs udev rules to process the new device. Udev rules use blkid to identify the device as an LVM PV and then execute the lvm-specific udev rule for the device, which triggers autoactivation.

There are two variations of event based autoactivation that may be used on a system, depending on the LVM udev rule that is installed (found in /lib/udev/rules.d/.) The following summarizes the steps in each rule which lead to autoactivation:

69-dm-lvm-metad.rules

•

device /dev/name with major:minor X:Y is attached to the machine

•

systemd/udev runs blkid to identify /dev/name as an LVM PV

•

udev rule 69-dm-lvm-metad.rules is run for /dev/name

•

the lvm udev rule runs the systemd service lvm2-pvscan@X:Yservice

•

the lvm2-pvscan service runs:

pvscan --cache -aay --major X --minor Y

•

pvscan reads the device, records that the PV is online (see pvs_online), and checks if the VG is complete.

•

if the VG is complete, pvscan creates the vgs_online temp file, and activates the VG.

•

the activation command output can be seen from systemctl status lvm2-pvscan*

69-dm-lvm.rules

•

device /dev/name with major:minor X:Y is attached to the machine

•

systemd/udev runs blkid to identify /dev/name as an LVM PV

•

udev rule 69-dm-lvm.rules is run for /dev/name

•

the lvm udev rule runs:

pvscan --cache --listvg --checkcomplete --vgonline

--autoactivation event --udevoutput --journal=output /dev/name

•

pvscan reads the device, records that the PV is online (see pvs_online), and checks if the VG is complete.

•

if the VG is complete, pvscan creates the vgs_online temp file, and prints the name of the VG for the udev rule to import: LVM_VG_NAME_COMPLETE='vgname'

•

if the lvm udev rule sees LVM_VG_NAME_COMPLETE from pvscan, it activates the VG using a transient systemd service named lvm-activate-<vgname>.

•

the lvm-activate-<vgname> service runs

vgchange -aay --autoactivation event <vgname>

•

the activation command output can be seen from journalctl -u lvm-activate-<vgname>

### pvscan options
--cache

Read the <device> arg (and only that device), and record that the PV is online by creating the /run/lvm/pvs_online/<pvid> file containing the name of the VG and the device for the PV.

-aay

Activate the VG from the pvscan command (includes implicit --checkcomplete and --vgonline.)

--checkcomplete

Check if the VG is complete, i.e. all PVs are present on the system, by checking /run/lvm/pvs_online/<pvid> files.

--vgonline

Create /run/lvm/vgs_online/<vgname> if the VG is complete (used to ensure only one command performs activation.)

--autoactivation event

Inform the command it is used for event based autoactivation.

--listvg

Print the name of the VG using the device.

--udevoutput

Only print output that can be imported to the udev rule, using the udev environment key format, i.e. NAME='value'.

--journal=output

Send standard command output to the journal (when stdout is reserved for udev output.)

### run files
Autoactivation commands use a number of temp files in /run/lvm (with the expectation that /run is cleared between boots.)

pvs_online

pvscan --cache creates a file here for each PV that is attached. The file is named with the PVID and contains the VG name and device information. The existence of the file is used to determine when all PVs for a given VG are present. The device information in these files is also used to optimize locating devices for a VG when the VG is activated.

pvs_lookup

pvscan --cache creates a file here named for a VG (if one doesn't already exist.) The file contains a list of PVIDs in the VG. This is needed when a PV is processed which has no VG metadata, in which case the list of PVIDs from the lookup file is used to check if the VG is complete.

vgs_online

The first activation command (pvscan or vgchange) to create a file here, named for the VG, will activate the VG. This resolves a race when concurrent commands attempt to activate a VG at once.

### static autoactivation
A static autoactivation method is no longer provided by lvm. Setting event_activation=0 still disables event based autoactivation. WARNING: disabling event activation without an alternative may prevent a system from booting. A custom systemd service could be written to run autoactivation during system startup, in which case disabling event autoactivation may be useful.

## EXAMPLES
VG "vg" contains two PVs:

```
$ pvs -o name,vgname,uuid /dev/sdb /dev/sdc

  PV         VG PV UUID

  /dev/sdb   vg 1uKpaT-lFOZ-NLHX-j4jI-OBi1-QpdE-HZ5hZY

  /dev/sdc   vg 5J3tM8-aIPe-2vbd-DBe7-bvRq-TGj0-DaKV2G
```

use of --cache:

```
$ pvscan --cache /dev/sdb

  pvscan[12922] PV /dev/sdb online.
$ pvscan --cache /dev/sdc

  pvscan[12923] PV /dev/sdc online.
$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY
8:16
vg:vg
dev:/dev/sdb
$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G
8:32
vg:vg
dev:/dev/sdc
```

use of -aay:

```
$ pvscan --cache -aay /dev/sdb

  pvscan[12935] PV /dev/sdb online, VG vg incomplete (need 1).
$ pvscan --cache -aay /dev/sdc

  pvscan[12936] PV /dev/sdc online, VG vg is complete.

  pvscan[12936] VG vg run autoactivation.

  1 logical volume(s) in volume group "vg" now active
$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY
8:16
vg:vg
dev:/dev/sdb
$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G
8:32
vg:vg
dev:/dev/sdc
$ ls /run/lvm/vgs_online/vg
/run/lvm/vgs_online/vg
```

use of --listvg:

```
$ pvscan --cache --listvg /dev/sdb

  VG vg
$ pvscan --cache --listvg /dev/sdc

  VG vg
$ cat /run/lvm/pvs_online/1uKpaTlFOZNLHXj4jIOBi1QpdEHZ5hZY
8:16
vg:vg
dev:/dev/sdb
$ cat /run/lvm/pvs_online/5J3tM8aIPe2vbdDBe7bvRqTGj0DaKV2G
8:32
vg:vg
dev:/dev/sdc
```

use of --checkcomplete:

```
$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdb

  pvscan[12996] PV /dev/sdb online, VG vg incomplete (need 1).

  VG vg incomplete
$ pvscan --cache --listvg --checkcomplete --vgonline /dev/sdc

  pvscan[12997] PV /dev/sdc online, VG vg is complete.

  VG vg complete
```

use of --udevoutput:

```
$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdb
LVM_VG_NAME_INCOMPLETE='vg'
$ pvscan --cache --listvg --checkcomplete --vgonline --udevoutput /dev/sdc
LVM_VG_NAME_COMPLETE='vg'
```

use of --listlvs:

```
$ lvs -o name,devices vg

  LV    Devices

  lvol0 /dev/sdb(0)

  lvol1 /dev/sdc(0)

  lvol2 /dev/sdb(1),/dev/sdc(1)
$ pvscan --cache --listlvs --checkcomplete /dev/sdb

  pvscan[13288] PV /dev/sdb online, VG vg incomplete (need 1).

  VG vg incomplete

  LV vg/lvol0 complete

  LV vg/lvol2 incomplete
$ pvscan --cache --listlvs --checkcomplete /dev/sdc

  pvscan[13289] PV /dev/sdc online, VG vg is complete.

  VG vg complete

  LV vg/lvol1 complete

  LV vg/lvol2 complete
```


lvmcache

title: lvmcache(7)

summary: LVM caching

text:
# lvmcache(7)

## NAME
lvmcache — LVM caching

## DESCRIPTION
lvm(8) includes two kinds of caching that can be used to improve the performance of a Logical Volume (LV). When caching, varying subsets of an LV's data are temporarily stored on a smaller, faster device (e.g. an SSD) to improve the performance of the LV.

To do this with lvm, a new special LV is first created from the faster device. This LV will hold the cache. Then, the new fast LV is attached to the main LV by way of an lvconvert command. lvconvert inserts one of the device mapper caching targets into the main LV's i/o path. The device mapper target combines the main LV and fast LV into a hybrid device that looks like the main LV, but has better performance. While the main LV is being used, portions of its data will be temporarily and transparently stored on the special fast LV.

The two kinds of caching are:

•

A read and write hot-spot cache, using the dm-cache kernel module. This cache tracks access patterns and adjusts its content deliberately so that commonly used parts of the main LV are likely to be found on the fast storage. LVM refers to this using the LV type cache.

•

A write cache, using the dm-writecache kernel module. This cache can be used with SSD or PMEM devices to speed up all writes to the main LV. Data read from the main LV is not stored in the cache, only newly written data. LVM refers to this using the LV type writecache.

## USAGE

### 1. Identify main LV that needs caching
The main LV may already exist, and is located on larger, slower devices. A main LV would be created with a command like:

\# lvcreate -n main -L Size vg /dev/slow_hhd

### 2. Identify fast LV to use as the cache
A fast LV is created using one or more fast devices, like an SSD. This special LV will be used to hold the cache:

\# lvcreate -n fast -L Size vg /dev/fast_ssd

\# lvs -a

LV Attr Type Devices

fast -wi------- linear /dev/fast_ssd

main -wi------- linear /dev/slow_hhd

### 3. Start caching the main LV
To start caching the main LV, convert the main LV to the desired caching type, and specify the fast LV to use as the cache:

using dm-cache (with cachepool):

\# lvconvert --type cache --cachepool fast vg/main

using dm-cache (with cachevol):

\# lvconvert --type cache --cachevol fast vg/main

using dm-writecache (with cachevol):

\# lvconvert --type writecache --cachevol fast vg/main

For more alteratives see:

dm-cache command shortcut

dm-cache with separate data and metadata LVs

### 4. Display LVs
Once the fast LV has been attached to the main LV, lvm reports the main LV type as either cache or writecache depending on the type used. While attached, the fast LV is hidden, and renamed with a _cvol or _cpool suffix. It is displayed by lvs -a. The _corig or _wcorig LV represents the original LV without the cache.

using dm-cache (with cachepool):

\# lvs -ao+devices

```
  LV                 Pool         Type       Devices

  main               [fast_cpool] cache      main_corig(0)

  [fast_cpool]                    cache-pool fast_pool_cdata(0)

  [fast_cpool_cdata]              linear     /dev/fast_ssd

  [fast_cpool_cmeta]              linear     /dev/fast_ssd

  [main_corig]                    linear     /dev/slow_hhd
```

using dm-cache (with cachevol):

\# lvs -ao+devices

```
  LV           Pool        Type   Devices

  main         [fast_cvol] cache  main_corig(0)

  [fast_cvol]              linear /dev/fast_ssd

  [main_corig]             linear /dev/slow_hhd
```

using dm-writecache (with cachevol):

\# lvs -ao+devices

```
  LV            Pool        Type       Devices

  main          [fast_cvol] writecache main_wcorig(0)

  [fast_cvol]               linear     /dev/fast_ssd

  [main_wcorig]             linear     /dev/slow_hhd
```

### 5. Use the main LV
Use the LV until the cache is no longer wanted, or needs to be changed.

### 6. Stop caching
To stop caching the main LV and also remove unneeded cache pool, use the --uncache:

\# lvconvert --uncache vg/main

\# lvs -a

```
  LV   VG Attr       Type   Devices

  main vg -wi------- linear /dev/slow_hhd
```

To stop caching the main LV, separate the fast LV from the main LV. This changes the type of the main LV back to what it was before the cache was attached.

\# lvconvert --splitcache vg/main

\# lvs -a

```
  LV   VG Attr       Type   Devices

  fast vg -wi------- linear /dev/fast_ssd

  main vg -wi------- linear /dev/slow_hhd
```

### 7. Create a new LV with caching
A new LV can be created with caching attached at the time of creation using the following command:

```
# lvcreate --type cache|writecache -n Name -L Size
	--cachedevice /dev/fast_ssd vg /dev/slow_hhd
```

The main LV is created with the specified Name and Size from the slow_hhd. A hidden fast LV is created on the fast_ssd and is then attached to the new main LV. If the fast_ssd is unused, the entire disk will be used as the cache unless the --cachesize option is used to specify a size for the fast LV. The --cachedevice option can be repeated to use multiple disks for the fast LV.

## OPTIONS

### option args
--cachepool CachePoolLV|LV

Pass this option a cachepool LV or a standard LV. When using a cache pool, lvm places cache data and cache metadata on different LVs. The two LVs together are called a cache pool. This has a bit better performance for dm-cache and permits specific placement and segment type selection for data and metadata volumes. A cache pool is represented as a special type of LV that cannot be used directly. If a standard LV is passed with this option, lvm will first convert it to a cache pool by combining it with another LV to use for metadata. This option can be used with dm-cache.

--cachevol LV

Pass this option a fast LV that should be used to hold the cache. With a cachevol, cache data and metadata are stored in different parts of the same fast LV. This option can be used with dm-writecache or dm-cache.

--cachedevice PV

This option can be used in place of --cachevol, in which case a cachevol LV will be created using the specified device. This option can be repeated to create a cachevol using multiple devices, or a tag name can be specified in which case the cachevol will be created using any of the devices with the given tag. If a named cache device is unused, the entire device will be used to create the cachevol. To create a cachevol of a specific size from the cache devices, include the --cachesize option.

### dm-cache block size
A cache pool will have a logical block size of 4096 bytes if it is created on a device with a logical block size of 4096 bytes.

If a main LV has logical block size 512 (with an existing xfs file system using that size), then it cannot use a cache pool with a 4096 logical block size. If the cache pool is attached, the main LV will likely fail to mount.

To avoid this problem, use a mkfs option to specify a 4096 block size for the file system, or attach the cache pool before running mkfs.

### dm-writecache block size
The dm-writecache block size can be 4096 bytes (the default), or 512 bytes. The default 4096 has better performance and should be used except when 512 is necessary for compatibility. The dm-writecache block size is specified with --cachesettings block_size=4096|512 when caching is started.

When a file system like xfs already exists on the main LV prior to caching, and the file system is using a block size of 512, then the writecache block size should be set to 512. (The file system will likely fail to mount if writecache block size of 4096 is used in this case.)

Check the xfs sector size while the fs is mounted:

\# xfs_info /dev/vg/main

```
Look for sectsz=512 or sectsz=4096
```

The writecache block size should be chosen to match the xfs sectsz value.

It is also possible to specify a sector size of 4096 to mkfs.xfs when creating the file system. In this case the writecache block size of 4096 can be used.

The writecache block size is displayed by the command:

lvs -o writecacheblocksize VG/LV

### dm-writecache memory usage
The amount of main system memory used by dm-writecache can be a factor when selecting the writecache cachevol size and the writecache block size.

•

writecache block size 4096: each 100 GiB of writecache cachevol uses slighly over 2 GiB of system memory.

•

writecache block size 512: each 100 GiB of writecache cachevol uses a little over 16 GiB of system memory.

### dm-writecache settings
To specify dm-writecache tunable settings on the command line, use:

--cachesettings 'option=N' or

--cachesettings 'option1=N option2=N ...'

For example, --cachesettings 'high_watermark=90 writeback_jobs=4'.

To include settings when caching is started, run:

```
# lvconvert --type writecache --cachevol fast \
	--cachesettings 'option=N' vg/main
```

To change settings for an existing writecache, run:

```
# lvchange --cachesettings 'option=N' vg/main
```

To clear all settings that have been applied, run:

```
# lvchange --cachesettings '' vg/main
```

To view the settings that are applied to a writecache LV, run:

```
# lvs -o cachesettings vg/main
```

Tunable settings are:

high_watermark = <percent>

Start writeback when the writecache usage reaches this percent (0-100).

low_watermark = <percent>

Stop writeback when the writecache usage reaches this percent (0-100).

writeback_jobs = <count>

Limit the number of blocks that are in flight during writeback. Setting this value reduces writeback throughput, but it may improve latency of read requests.

autocommit_blocks = <count>

When the application writes this amount of blocks without issuing the FLUSH request, the blocks are automatically commited.

autocommit_time = <milliseconds>

The data is automatically commited if this time passes and no FLUSH request is received.

fua = 0|1

Use the FUA flag when writing data from persistent memory back to the underlying device. Applicable only to persistent memory.

nofua = 0|1

Don't use the FUA flag when writing back data and send the FLUSH request afterwards. Some underlying devices perform better with fua, some with nofua. Testing is necessary to determine which. Applicable only to persistent memory.

cleaner = 0|1

Setting cleaner=1 enables the writecache cleaner mode in which data is gradually flushed from the cache. If this is done prior to detaching the writecache, then the splitcache command will have little or no flushing to perform. If not done beforehand, the splitcache command enables the cleaner mode and waits for flushing to complete before detaching the writecache. Adding cleaner=0 to the splitcache command will skip the cleaner mode, and any required flushing is performed in device suspend.

### dm-writecache using metadata profiles
In addition to specifying writecache settings on the command line, they can also be set in lvm.conf, or in a profile file, using the allocation/cache_settings/writecache config structure shown below.

It's possible to prepare a number of different profile files in the /etc/lvm/profile directory and specify the file name of the profile when starting writecache.

Example

```
# cat <<EOF > /etc/lvm/profile/cache_writecache.profile
allocation {
```

```
cache_settings {
```

```
writecache {
```

```
high_watermark=60
writeback_jobs=1024
```

```
}
```

```
}
```

```
}
EOF
```

```
# lvcreate -an -L10G --name fast vg /dev/fast_ssd
# lvcreate --type writecache -L10G --name main  --cachevol fast \

   --metadataprofile cache_writecache vg /dev/slow_hdd
```

### dm-cache with separate data and metadata LVs
Preferred way of using dm-cache is to place the cache metadata and cache data on separate LVs. To do this, a "cache pool" is created, which is a special LV that references two sub LVs, one for data and one for metadata.

To create a cache pool of given data size and let lvm2 calculate appropriate metadata size:

\# lvcreate --type cache-pool -L DataSize -n fast vg /dev/fast_ssd1

To create a cache pool from separate LV and let lvm2 calculate appropriate cache metadata size:

\# lvcreate -n fast -L DataSize vg /dev/fast_ssd1

\# lvconvert --type cache-pool vg/fast /dev/fast_ssd1

To create a cache pool from two separate LVs:

\# lvcreate -n fast -L DataSize vg /dev/fast_ssd1

\# lvcreate -n fastmeta -L MetadataSize vg /dev/fast_ssd2

\# lvconvert --type cache-pool --poolmetadata fastmeta vg/fast

Then use the cache pool LV to start caching the main LV:

\# lvconvert --type cache --cachepool fast vg/main

A variation of the same procedure automatically creates a cache pool when caching is started. To do this, use a standard LV as the --cachepool (this will hold cache data), and use another standard LV as the --poolmetadata (this will hold cache metadata). LVM will create a cache pool LV from the two specified LVs, and use the cache pool to start caching the main LV.

```
# lvcreate -n fast -L DataSize vg /dev/fast_ssd1
# lvcreate -n fastmeta -L MetadataSize vg /dev/fast_ssd2
# lvconvert --type cache --cachepool fast \

        --poolmetadata fastmeta vg/main
```

### dm-cache cache modes
The default dm-cache cache mode is "writethrough". Writethrough ensures that any data written will be stored both in the cache and on the origin LV. The loss of a device associated with the cache in this case would not mean the loss of any data.

A second cache mode is "writeback". Writeback delays writing data blocks from the cache back to the origin LV. This mode will increase performance, but the loss of a cache device can result in lost data.

With the --cachemode option, the cache mode can be set when caching is started, or changed on an LV that is already cached. The current cache mode can be displayed with the cache_mode reporting option:

lvs -o+cache_mode VG/LV

lvm.conf(5) allocation/cache_mode

defines the default cache mode.

```
# lvconvert --type cache --cachemode writethrough \

        --cachepool fast vg/main
```

```
# lvconvert --type cache --cachemode writethrough \

        --cachevol fast  vg/main
```

### dm-cache chunk size
The size of data blocks managed by dm-cache can be specified with the --chunksize option when caching is started. The default unit is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB. Cache chunks bigger then 512KiB shall be only used when necessary.

Using a chunk size that is too large can result in wasteful use of the cache, in which small reads and writes cause large sections of an LV to be stored in the cache. It can also require increasing migration threshold which defaults to 2048 sectors (1 MiB). Lvm2 ensures migration threshold is at least 8 chunks in size. This may in some cases result in very high bandwidth load of transfering data between the cache LV and its cache origin LV. However, choosing a chunk size that is too small can result in more overhead trying to manage the numerous chunks that become mapped into the cache. Overhead can include both excessive CPU time searching for chunks, and excessive memory tracking chunks.

Command to display the chunk size:

lvs -o+chunksize VG/LV

lvm.conf(5) allocation/cache_pool_chunk_size

controls the default chunk size.

The default value is shown by:

lvmconfig --type default allocation/cache_pool_chunk_size

Checking migration threshold (in sectors) of running cached LV:

lvs -o+kernel_cache_settings VG/LV

### dm-cache migration threshold
Migrating data between the origin and cache LV uses bandwidth. The user can set a throttle to prevent more than a certain amount of migration occurring at any one time. Currently dm-cache is not taking any account of normal io traffic going to the devices.

User can set migration threshold via cache policy settings as "migration_threshold=<#sectors>" to set the maximum number of sectors being migrated, the default being 2048 sectors (1MiB).

Command to set migration threshold to 2MiB (4096 sectors):

lvcreate --cachepolicy 'migration_threshold=4096' VG/LV

Command to display the migration threshold:

lvs -o+kernel_cache_settings,cache_settings VG/LV

lvs -o+chunksize VG/LV

### dm-cache cache policy
The dm-cache subsystem has additional per-LV parameters: the cache policy to use, and possibly tunable parameters for the cache policy. Three policies are currently available: "smq" is the default policy, "mq" is an older implementation, and "cleaner" is used to force the cache to write back (flush) all cached writes to the origin LV.

The older "mq" policy has a number of tunable parameters. The defaults are chosen to be suitable for the majority of systems, but in special circumstances, changing the settings can improve performance.

With the --cachepolicy and --cachesettings options, the cache policy and settings can be set when caching is started, or changed on an existing cached LV (both options can be used together). The current cache policy and settings can be displayed with the cache_policy and cache_settings reporting options:

lvs -o+cache_policy,cache_settings VG/LV

Change the cache policy and settings of an existing LV.

```
# lvchange --cachepolicy mq --cachesettings \
	'migration_threshold=2048 random_threshold=4' vg/main
```

lvm.conf(5) allocation/cache_policy

defines the default cache policy.

lvm.conf(5) allocation/cache_settings

defines the default cache settings.

### dm-cache using metadata profiles
Cache pools allows to set a variety of options. Lots of these settings can be specified in lvm.conf or profile settings. You can prepare a number of different profiles in the /etc/lvm/profile directory and just specify the metadata profile file name when caching LV or creating cache-pool. Check the output of lvmconfig --type default --withcomments for a detailed description of all individual cache settings.

Example

```
# cat <<EOF > /etc/lvm/profile/cache_big_chunk.profile
allocation {
```

```
cache_pool_metadata_require_separate_pvs=0
cache_pool_chunk_size=512
cache_metadata_format=2
cache_mode="writethrough"
cache_policy="smq"
cache_settings {
```

```
smq {
```

```
migration_threshold=8192
random_threshold=4096
```

```
}
```

```
}
```

```
}
EOF
```

```
# lvcreate --cache -L10G --metadataprofile cache_big_chunk vg/main \

        /dev/fast_ssd
# lvcreate --cache -L10G vg/main --config \

        'allocation/cache_pool_chunk_size=512' /dev/fast_ssd
```

### dm-cache spare metadata LV
See lvmthin(7) for a description of the "pool metadata spare" LV. The same concept is used for cache pools.

### dm-cache metadata formats
There are two disk formats for dm-cache metadata. The metadata format can be specified with --cachemetadataformat when caching is started, and cannot be changed. Format 2 has better performance; it is more compact, and stores dirty bits in a separate btree, which improves the speed of shutting down the cache. With auto, lvm selects the best option provided by the current dm-cache kernel module.

### RAID1 cache device
RAID1 can be used to create the fast LV holding the cache so that it can tolerate a device failure. (When using dm-cache with separate data and metadata LVs, each of the sub-LVs can use RAID1.)

```
# lvcreate -n main -L Size vg /dev/slow
# lvcreate --type raid1 -m 1 -n fast -L Size vg /dev/ssd1 /dev/ssd2
# lvconvert --type cache --cachevol fast vg/main
```

### dm-cache command shortcut
A single command can be used to cache main LV with automatic creation of a cache-pool:

```
# lvcreate --cache --size CacheDataSize VG/LV [FastPVs]
```

or the longer variant

```
# lvcreate --type cache --size CacheDataSize \

        --name NameCachePool VG/LV [FastPVs]
```

In this command, the specified LV already exists, and is the main LV to be cached. The command creates a new cache pool with size and given name or the name is automatically selected from a sequence lvolX_cpool, using the optionally specified fast PV(s) (typically an ssd). Then it attaches the new cache pool to the existing main LV to begin caching.

(Note: ensure that the specified main LV is a standard LV. If a cache pool LV is mistakenly specified, then the command does something different.)

(Note: the type option is interpreted differently by this command than by normal lvcreate commands in which --type specifies the type of the newly created LV. In this case, an LV with type cache-pool is being created, and the existing main LV is being converted to type cache.)

## SEE ALSO
lvm.conf(5), lvchange(8), lvcreate(8), lvdisplay(8), lvextend(8), lvremove(8), lvrename(8), lvresize(8), lvs(8),

vgchange(8), vgmerge(8), vgreduce(8), vgsplit(8),

cache_check(8), cache_dump(8), cache_repair(8)