NAME

ggaoed.conf - configuration file for ggaoed

DESCRIPTION

This configuration file specifies the block devices that ggaoed exports using the AoE protocol.

The configuration file is organized into groups. Every group must start with the group name enclosed in square brackets. Inside a group there can be any number of key-value pairs specifying various options. Lines starting with a ‘#’ are treated as comments and are ignored.

There are two special groups named defaults and acls. The defaults group specifies global defaults, while the acls group specifies access control lists that can be referenced in device descriptions (see below).

Apart from the special groups mentioned above, there are two kinds of groups: if the name of the group matches the name of a network interface, then it contains settings for that network interface. Otherwise, it describes a device to export.

GLOBAL DEFAULTS

The following values can be configured in the defaults group:

queue-length

The default I/O queue length of a device. There may be this many simultaneous I/O requests active. Valid values are between 1 and 65535. The default is 64.

direct-io

If set to true, then devices will use direct I/O by default. Note that whether direct I/O will improve or reduce performance depends on a lot of factors. Valid values are true and false. The default value is true.

trace-io

If set to true, then all I/O requests received by the daemon will be logged. Note that this may produce a huge volume of messages on a heavy used server so this option should only be enabled for debugging purposes. Valid values are true and false. The default value is false.

interfaces

Comma-separated list of network interfaces where the daemon should listen on. The shell-like glob characters ‘?’ and ‘*’ are also allowed. If this parameter is not defined, ggaoed will listen on all up and running Ethernet interfaces.

mtu

Force the specified MTU rather than the auto-detected value. Note that you can only lower the MTU this way.

ring-buffer-size

Size of the ring buffer for sending and receiving packets combined, in KiB. Note that these buffers are allocated from unswappable kernel memory. The default value is 4096. Setting this value to 0 disables the memory-mapped ring buffer and forces ggaoed to use traditional recvmsg() and sendmsg() calls.

send-buffer-size

Size of the in-kernel socket buffer for sending data, in KiB. It is relevant only if the ring buffer is disabled. Note that this value is only a hint; check the logs if you want to know the real value being used.

receive-buffer-size

Size of the in-kernel socket buffer for receiving data, in KiB. It is relevant only if the ring buffer is disabled. Note that this value is only a hint; check the logs if you want to know the real value being used.

max-delay

When merging I/O requests, requests that have earlier may get repeatedly pushed at the end of the queue. This value specifies the bound for how long that can happen. The value should be a floating point number between 0 and 1.

merge-delay

When not zero, I/O submission will be delayed after receiving a request anticipating more requests to merge together. The value should be a floating point number between 0 and 1. The default is 0.

pid-file

The location of the pid file. The default value is /var/run/ggaoed.conf.

control-socket

The location of the control socket used by ggaoectl. The default value is /var/run/ggaoed.sock.

state-directory

The directory where persistent information (AoE configuration space, MAC mask list and reservation list) is stored. The default value is /var/ggaoed.

Example:

[defaults]
interfaces = eth2, vlan*
queue-length = 256
	

ACL DEFINITIONS

The acls group defines named access control lists that in turn can be referenced in device configuration groups. The group contains key-value pairs, where the key is the name of the defined ACL, and the value is a comma-separated list of addresses. The following addresses are recognized:

MAC address

Hardware ethernet address having the form XX:XX:XX:XX:XX:XX, where X stands for a hexadecimal digit.

A previously defined ACL

The value may be the name of a previously defined ACL. In this case the list of addresses defined by that ACL is appended to the current ACL.

Symbolic name

If a value cannot be interpreted by the above rules, then it is looked up in /etc/ethers.

Example:

[acls]
acl1 = de:ad:be:ef:00:01, de:ad:be:ef:00:02
acl2 = de:ad:be:ef:01:01, de:ad:be:ef:01:02
# Reference existing ACLs
acl3 = acl1, acl2
# Look up the MAC address in /etc/ethers
acl4 = somehost
	

An ACL can contain at most 255 entries. If the ACL definition resolves to more entries, then only the first 255 will be used.

NETWORK INTERFACE CONFIGURATION

If the name of a group matches the name of a network interface, then it describes configuration for that interface. The following options may be specified:

mtu

Force the specified MTU rather than the auto-detected value. Note that you can only lower the MTU this way.

ring-buffer-size

Size of the ring buffer for receiving packets, in KiB. Note that these buffers are allocated from unswappable kernel memory. The default value is 4096. Setting this value to 0 disables the memory-mapped ring buffer and forces ggaoed to use traditional sendmsg() and recvmsg() calls.

send-buffer-size

Size of the in-kernel socket buffer for sending data, in KiB. It is relevant only if the ring buffer is disabled. Note that this value is only a hint; check the logs if you want to know the real value being used.

receive-buffer-size

Size of the in-kernel socket buffer for receiving data, in KiB. It is relevant only if the ring buffer is disabled. Note that this value is only a hint; check the logs if you want to know the real value being used.

Example:

[eth0]
mtu = 4200
	

DISK DEVICE CONFIGURATION

If a group does not fall into the above categories, then it is interpreted as a disk device definition. In this case the name of the group is not really important except that it must be unique and it will be used for logging. The following options may be specified for a disk device:

path

Path of the block device or file to export. It cannot be used together with the uuid option. Specifying exactly one of the path and uuid options is mandatory.

uuid

UUID of the device to export. It cannot be used together with the path option. If the uuid option is specified, then all known block devices are scanned, and the one that has a known content with a matching UUID will be used. Devices that can be identified in this way include MD (software RAID) devices, LVM logical volumes, swap partitions, or any block device that contains a valid file system that supports UUIDs.

shelf

The AoE shelf address of the device. Specifying it is mandatory.

slot

The AoE slot address of the device. Specifying it is mandatory. The shelf/slot pair must be unique between configured devices.

queue-length

The number of I/O operations that can be queued simultaneously.

max-delay

When merging I/O requests, requests that have earlier may get repeatedly pushed at the end of the queue. This value specifies the bound for how long that can happen. The value should be a floating point number between 0 and 1.

merge-delay

When not zero, I/O submission will be delayed after receiving a request anticipating more requests to merge together. The value should be a floating point number between 0 and 1.

direct-io

If set to true, then the device will be opened using O_DIRECT. If set to false, buffered I/O will be used for this device.

trace-io

If set to true, then all I/O requests received by the daemon will be logged. Note that this may produce a huge volume of messages on a heavy used server so this option should only be enabled for debugging purposes. The default value is false. Setting this option to false in the per-device section disables I/O tracing even if the -d option was passed to ggaoed.

read-only

If set to true, the device or file will be opened in read-only mode, and all write operations to it will fail. The default is false.

interfaces

A comma-separated list of interfaces where the device should be exported. If not specified, the device can be accessed on all interfaces the daemon listens on.

accept

A comma-separated list of ACL entries where the device is allowed to receive commands from. See the description of the acls group on how the list is interpreted.

If the accept option is missing, the device accepts commands from all clients. If the accept option defines a non-empty list, then only clients whose MAC address is part of the ACL will be allowed access.

deny

A comma-separated list of ACL entries where the device should not accept commands from. This ACL is evaluated after the accept ACL.

broadcast

By default, the existence of the device will be broadcasted on all interfaces defined by the interfaces option. However, if the accept option specifies a non-empty ACL, then the presence of the device will be announced only to the hosts whose MAC address is part of the ACL. Setting this option to true reverts this behaviour. This can be used to reduce traffic if the accept ACL contains a large number of addresses.

Example:

[sdc]
path = /dev/sdc
shelf = 0
slot = 0
accept = acl3
broadcast = true
read-only = true
[somedisk]
uuid = 01234567-89ab-cdef-0123-456789abcdef
shelf = 0
slot = 1
queue-length = 64
	

SEE ALSO

ggaoed(8), ggaoectl(8)

AUTHOR

Gábor Gombás <gombasg@digikabel.hu>