package: systemd-portable

title: org.freedesktop.portable1(5)

summary: The D\-Bus interface of systemd\-portabled

text:
# org.freedesktop.portable1(5)

## NAME
org.freedesktop.portable1 - The D-Bus interface of systemd-portabled

## INTRODUCTION
systemd-portabled.service(8) is a system service that may be used to attach, detach and inspect portable services. This page describes the D-Bus interface.

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/portable1 {

  interface org.freedesktop.portable1.Manager {

    methods:

      GetImage(in  s image,

               out o object);

      ListImages(out a(ssbtttso) images);

      GetImageOSRelease(in  s image,

                        out a{ss} os_release);

      GetImageMetadata(in  s image,

                       in  as matches,

                       out s image,

                       out ay os_release,

                       out a{say} units);

      GetImageMetadataWithExtensions(in  s image,

                                     in  as extensions,

                                     in  as matches,

                                     in  t flags,

                                     out s image,

                                     out ay os_release,

                                     out a{say} extensions,

                                     out a{say} units);

      GetImageState(in  s image,

                    out s state);

      GetImageStateWithExtensions(in  s image,

                                  in  as extensions,

                                  in  t flags,

                                  out s state);

      AttachImage(in  s image,

                  in  as matches,

                  in  s profile,

                  in  b runtime,

                  in  s copy_mode,

                  out a(sss) changes);

      AttachImageWithExtensions(in  s image,

                                in  as extensions,

                                in  as matches,

                                in  s profile,

                                in  s copy_mode,

                                in  t flags,

                                out a(sss) changes);

      DetachImage(in  s image,

                  in  b runtime,

                  out a(sss) changes);

      DetachImageWithExtensions(in  s image,

                                in  as extensions,

                                in  t flags,

                                out a(sss) changes);

      ReattachImage(in  s image,

                    in  as matches,

                    in  s profile,

                    in  b runtime,

                    in  s copy_mode,

                    out a(sss) changes_removed,

                    out a(sss) changes_updated);

      ReattachImageWithExtensions(in  s image,

                                  in  as extensions,

                                  in  as matches,

                                  in  s profile,

                                  in  s copy_mode,

                                  in  t flags,

                                  out a(sss) changes_removed,

                                  out a(sss) changes_updated);

      RemoveImage(in  s image);

      MarkImageReadOnly(in  s image,

                        in  b read_only);

      SetImageLimit(in  s image,

                    in  t limit);

      SetPoolLimit(in  t limit);

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s PoolPath = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t PoolUsage = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t PoolLimit = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly as Profiles = ['...', ...];

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
GetImage() may be used to get the image object path of the image with the specified name.

ListImages() returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation time, modification time, current disk space, usage and image object path.

GetImageOSRelease() retrieves the OS release information of an image. This method returns an array of key value pairs read from the os-release(5) file in the image and is useful to identify the operating system used in a portable service.

GetImageMetadata() retrieves metadata associated with an image. This method returns the image name, the image's os-release(5) content in the form of a (streamable) array of bytes, and a list of portable units contained in the image, in the form of a string (unit name) and an array of bytes with the content.

GetImageMetadataWithExtensions() retrieves metadata associated with an image. This method is a superset of GetImageMetadata() with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via AttachImageWithExtensions(). The path of each extension and an array of bytes with the content of the respective extension-release file are returned, one such structure for each extension named in the input arguments.

GetImageState() retrieves the image state as one of the following strings:

•detached

•attached

•attached-runtime

•enabled

•enabled-runtime

•running

•running-runtime

GetImageStateWithExtensions() is a superset of GetImageState(), with additional support for a list of extensions as input parameters, which is necessary to query the state in case the image was attached in that particular way. The flag parameter is currently unused and reserved for future purposes.

AttachImage() attaches a portable image to the system. This method takes an image path or name, a list of strings that will be used to search for unit files inside the image (partial or complete matches), a string indicating which portable profile to use for the image (see Profiles property for a list of available profiles), a boolean indicating whether to attach the image only for the current boot session, and a string representing the preferred copy mode (whether to copy the image or to just symlink it) with the following possible values:

•(empty)

•copy

•symlink

•mixed

If an empty string is passed the security profile drop-ins and images will be symlinked while unit files will be copied, copy will copy, symlink will prefer linking if possible (e.g.: a unit has to be copied out of an image), and mixed will prefer linking the resources owned by the OS (e.g.: the portable profile located within the host's /usr/ tree) but will copy the resources owned by the portable image (e.g.: the unit files and the images). This method returns the list of changes applied to the system (for example, which unit was added and is now available as a system service). Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any). The type of change applied will be one of the following possible values:

•copy

•symlink

•write

•mkdir

Note that an image cannot be attached if a unit that it contains is already present on the system. Note that this method returns only after all the listed operations are completed, and due to the I/O involved it might take some time.

In place of the image path a ".v/" versioned directory may be specified, see systemd.v(7) for details.

In place of the directory path a ".v/" versioned directory may be specified, see systemd.v(7) for details.

AttachImageWithExtensions() attaches a portable image to the system. This method is a superset of AttachImage() with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image. When this method is used, detaching must be done by passing the same arguments via the DetachImageWithExtensions() method. For more details on this functionality, see the MountImages= entry on systemd.exec(5) and systemd-sysext(8).

DetachImage() detaches a portable image from the system. This method takes an image path or name, and a boolean indicating whether the image to detach was attached only for the current boot session or persistently. This method returns the list of changes applied to the system (for example, which unit was removed and is no longer available as a system service). Each change is represented as a triplet of strings: the type of change applied, the path on which it was applied, and the source (if any). The type of change applied will be one of the following possible values:

•unlink

Note that an image cannot be detached if a unit that it contains is running. Note that this method returns only after all the listed operations are completed, and due to the I/O involved it might take some time.

DetachImageWithExtensions() detaches a portable image from the system. This method is a superset of DetachImage() with the addition of a list of extensions as input parameter, which were overlaid on top of the main image via AttachImageWithExtensions().

ReattachImage() combines the effects of the AttachImage() method and the DetachImage() method. The difference is that it is allowed to reattach an image while one or more of its units are running. The reattach operation will fail if no matching image is attached. The input parameters match the AttachImage() method, and the return parameters are the combination of the return parameters of the DetachImage() method (first array, units that were removed) and the AttachImage() method (second array, units that were updated or added).

ReattachImageWithExtensions() reattaches a portable image to the system. This method is a superset of ReattachImage() with the addition of a list of extensions as input parameter, which will be overlaid on top of the main image. For more details on this functionality, see the MountImages= entry on systemd.exec(5) and systemd-sysext(8).

RemoveImage() removes the image with the specified name.

MarkImageReadOnly() toggles the read-only flag of an image.

SetPoolLimit() sets an overall quota limit on the pool of images.

SetImageLimit() sets a per-image quota limit.

The AttachImageWithExtensions(), DetachImageWithExtensions() and ReattachImageWithExtensions() methods take in options as flags instead of booleans to allow for extendability. SD_SYSTEMD_PORTABLE_FORCE_ATTACH will bypass the safety checks that ensure the units are not running while the image is attached or detached. SD_SYSTEMD_PORTABLE_FORCE_EXTENSION will bypass the check that ensures the extension-release.NAME file in the extension image matches the image name. They are defined as follows:

```
#define SD_SYSTEMD_PORTABLE_RUNTIME            (UINT64_C(1) << 0)
#define SD_SYSTEMD_PORTABLE_FORCE_ATTACH       (UINT64_C(1) << 1)
#define SD_SYSTEMD_PORTABLE_FORCE_EXTENSION    (UINT64_C(1) << 2)
```

### Properties
PoolPath specifies the file system path where images are written to.

PoolUsage specifies the current usage size of the image pool in bytes.

PoolLimit specifies the size limit of the image pool in bytes.

Profiles specifies the available runtime profiles for portable services.

## THE IMAGE OBJECT
The service exposes the following interfaces on the Image object on the bus:

```
node /org/freedesktop/portable1 {

  interface org.freedesktop.portable1.Image {

    methods:

      GetOSRelease(out a{ss} os_release);

      GetMetadata(in  as matches,

                  out s image,

                  out ay os_release,

                  out a{say} units);

      GetMetadataWithExtensions(in  as extensions,

                                in  as matches,

                                in  t flags,

                                out s image,

                                out ay os_release,

                                out a{say} extensions,

                                out a{say} units);

      GetState(out s state);

      GetStateWithExtensions(in  as extensions,

                             in  t flags,

                             out s state);

      Attach(in  as matches,

             in  s profile,

             in  b runtime,

             in  s copy_mode,

             out a(sss) changes);

      AttachWithExtensions(in  as extensions,

                           in  as matches,

                           in  s profile,

                           in  s copy_mode,

                           in  t flags,

                           out a(sss) changes);

      Detach(in  b runtime,

             out a(sss) changes);

      DetachWithExtensions(in  as extensions,

                           in  t flags,

                           out a(sss) changes);

      Reattach(in  as matches,

               in  s profile,

               in  b runtime,

               in  s copy_mode,

               out a(sss) changes_removed,

               out a(sss) changes_updated);

      ReattachWithExtensions(in  as extensions,

                             in  as matches,

                             in  s profile,

                             in  s copy_mode,

                             in  t flags,

                             out a(sss) changes_removed,

                             out a(sss) changes_updated);

      Remove();

      MarkReadOnly(in  b read_only);

      SetLimit(in  t limit);

    properties:

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s Name = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s Path = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s Type = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly b ReadOnly = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t CreationTimestamp = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t ModificationTimestamp = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t Usage = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t Limit = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t UsageExclusive = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t LimitExclusive = ...;

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

### Methods
The following methods implement the same operation as the respective methods on the Manager object (see above). However, these methods operate on the image object and hence does not take an image name parameter. Invoking the methods directly on the Manager object has the advantage of not requiring a GetImage() call to get the image object for a specific image name. Calling the methods on the Manager object is hence a round trip optimization. List of methods:

•GetOSRelease()

•GetMetadata()

•GetMetadataWithExtensions()

•GetState()

•Attach()

•AttachWithExtensions()

•Detach()

•DetachWithExtensions()

•Reattach()

•ReattachWithExtensions()

•Remove()

•MarkReadOnly()

•SetLimit()

### Properties
Name specifies the image name.

Path specifies the file system path where image is stored.

Type specifies the image type.

ReadOnly specifies whether the image is read-only.

CreationTimestamp specifies the image creation timestamp.

ModificationTimestamp specifies the image modification timestamp.

Usage specifies the image disk usage.

Limit specifies the image disk usage limit.

UsageExclusive specifies the image disk usage (exclusive).

LimitExclusive specifies the image disk usage limit (exclusive).

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[1].

## HISTORY

### The Manager Object
GetImageStateWithExtensions() was added in version 251.

### The Image Object
GetStateWithExtensions() was added in version 251.

ReattachWithExtensions() was added in version 254.

## SEE ALSO
systemd(1), systemd-portabled.service(8), portablectl(1)

## NOTES
1.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html


package: systemd-timesyncd

title: org.freedesktop.timesync1(5)

summary: The D\-Bus interface of systemd\-timesyncd

text:
# org.freedesktop.timesync1(5)

## NAME
org.freedesktop.timesync1 - The D-Bus interface of systemd-timesyncd

## INTRODUCTION
systemd-timesyncd.service(8) is a system service that may be used to synchronize the local system clock with a remote Network Time Protocol (NTP) server. This page describes the D-Bus interface.

## THE MANAGER OBJECT
The service exposes the following interfaces on the Manager object on the bus:

```
node /org/freedesktop/timesync1 {

  interface org.freedesktop.timesync1.Manager {

    methods:

      SetRuntimeNTPServers(in  as runtime_servers);

    properties:

      readonly as LinkNTPServers = ['...', ...];

      readonly as SystemNTPServers = ['...', ...];

      readonly as RuntimeNTPServers = ['...', ...];

      readonly as FallbackNTPServers = ['...', ...];

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly s ServerName = '...';

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly (iay) ServerAddress = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t RootDistanceMaxUSec = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t PollIntervalMinUSec = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")

      readonly t PollIntervalMaxUSec = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly t PollIntervalUSec = ...;

      readonly (uuuuittayttttbtt) NTPMessage = ...;

      @org.freedesktop.DBus.Property.EmitsChangedSignal("false")

      readonly x Frequency = ...;

  };

  interface org.freedesktop.DBus.Peer { ... };

  interface org.freedesktop.DBus.Introspectable { ... };

  interface org.freedesktop.DBus.Properties { ... };
};
```

Provides information about the manager.

## EXAMPLES
Example 1. Introspect org.freedesktop.timesync1.Manager on the bus

```
$ gdbus introspect --system \

  --dest org.freedesktop.timesync1 \

  --object-path /org/freedesktop/timesync1
```

## VERSIONING
These D-Bus interfaces follow the usual interface versioning guidelines[1].

## SEE ALSO
systemd(1), systemd-timesyncd.service(8)

## NOTES
1.

the usual interface versioning guidelines

https://0pointer.de/blog/projects/versioning-dbus.html


timesyncd.conf

title: timesyncd.conf(5)

text:
# timesyncd.conf(5)

## NAME
timesyncd.conf, timesyncd.conf.d - Network Time Synchronization configuration files

## SYNOPSIS
/etc/systemd/timesyncd.conf

/run/systemd/timesyncd.conf

/usr/local/lib/systemd/timesyncd.conf

/usr/lib/systemd/timesyncd.conf

/etc/systemd/timesyncd.conf.d/*.conf

/run/systemd/timesyncd.conf.d/*.conf

/usr/local/lib/systemd/timesyncd.conf.d/*.conf

/usr/lib/systemd/timesyncd.conf.d/*.conf

## DESCRIPTION
These configuration files control NTP network time synchronization. See systemd.syntax(7) for a general description of the syntax.

## CONFIGURATION DIRECTORIES AND PRECEDENCE
The default configuration is set during compilation, so configuration is only needed when it is necessary to deviate from those defaults. The main configuration file is loaded from one of the listed directories in order of priority, only the first file found is used: /etc/systemd/, /run/systemd/, /usr/local/lib/systemd/ [1], /usr/lib/systemd/. The vendor version of the file contains commented out entries showing the defaults as a guide to the administrator. Local overrides can also be created by creating drop-ins, as described below. The main configuration file can also be edited for this purpose (or a copy in /etc/ if it is shipped under /usr/), however using drop-ins for local configuration is recommended over modifications to the main configuration file.

In addition to the main configuration file, drop-in configuration snippets are read from /usr/lib/systemd/*.conf.d/, /usr/local/lib/systemd/*.conf.d/, and /etc/systemd/*.conf.d/. Those drop-ins have higher precedence and override the main configuration file. Files in the *.conf.d/ configuration subdirectories are sorted by their filename in lexicographic order, regardless of in which of the subdirectories they reside. When multiple files specify the same option, for options which accept just a single value, the entry in the file sorted last takes precedence, and for options which accept a list of values, entries are collected as they occur in the sorted files.

When packages need to customize the configuration, they can install drop-ins under /usr/. Files in /etc/ are reserved for the local administrator, who may use this logic to override the configuration files installed by vendor packages. Drop-ins have to be used to override package drop-ins, since the main configuration file has lower precedence. It is recommended to prefix all filenames in those subdirectories with a two-digit number and a dash, to simplify the ordering. This also defines a concept of drop-in priorities to allow OS vendors to ship drop-ins within a specific range lower than the range used by users. This should lower the risk of package drop-ins overriding accidentally drop-ins defined by users. It is recommended to use the range 10-40 for drop-ins in /usr/ and the range 60-90 for drop-ins in /etc/ and /run/, to make sure that local and transient drop-ins take priority over drop-ins shipped by the OS vendor.

To disable a configuration file supplied by the vendor, the recommended way is to place a symlink to /dev/null in the configuration directory in /etc/, with the same filename as the vendor configuration file.

## OPTIONS
The following settings are configured in the [Time] section:

NTP=

A space-separated list of NTP server host names or IP addresses. During runtime this list is combined with any per-interface NTP servers acquired from systemd-networkd.service(8). systemd-timesyncd will contact all configured system or per-interface servers in turn, until one responds. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect. This setting defaults to an empty list. Added in version 216.

FallbackNTP=

A space-separated list of NTP server host names or IP addresses to be used as the fallback NTP servers. Any per-interface NTP servers obtained from systemd-networkd.service(8) take precedence over this setting, as do any servers set via NTP= above. This setting is hence only relevant if no other NTP server information is known. When the empty string is assigned, the list of NTP servers is reset, and all prior assignments will have no effect. If this option is not given, a compiled-in list of NTP servers is used. Added in version 216.

RootDistanceMaxSec=

Maximum acceptable root distance, i.e. the maximum estimated time required for a packet to travel to the server we are connected to from the server with the reference clock. If the current server does not satisfy this limit, systemd-timesyncd will switch to a different server. Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time(7). Defaults to 5 seconds.

Added in version 236.

PollIntervalMinSec=, PollIntervalMaxSec=

The minimum and maximum poll intervals for NTP messages. Polling starts at the minimum poll interval, and is adjusted within the specified limits in response to received packets. Each setting takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time(7). PollIntervalMinSec= defaults to 32 seconds and must not be smaller than 16 seconds. PollIntervalMaxSec= defaults to 34 min 8 s (2048 seconds) and must be larger than PollIntervalMinSec=.

Added in version 236.

ConnectionRetrySec=

Specifies the minimum delay before subsequent attempts to contact a new NTP server are made. Takes a time span value. The default unit is seconds, but other units may be specified, see systemd.time(7). Defaults to 30 seconds and must not be smaller than 1 second.

Added in version 248.

SaveIntervalSec=

The interval at which the current time is periodically saved to disk, in the absence of any recent synchronisation from an NTP server. This is especially useful for offline systems with no local RTC, as it will guarantee that the system clock remains roughly monotonic across reboots. Takes a time interval value. The default unit is seconds, but other units may be specified, see systemd.time(7). Defaults to 60 seconds.

Added in version 250.

## SEE ALSO
systemd(1), systemd-timesyncd.service(8), systemd-networkd.service(8)

## NOTES
1.

💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.


initctl

package: sysvinit

title: initctl(5)

text:
# initctl(5)

## NAME
initctl - /dev/initctl is a named pipe which passes commands to SysV init.

## SYNOPSIS
/dev/initctl

## DESCRIPTION
This document describes the communiction pipe set up by SysV init at /dev/initctl. This named pipe allows programs with the proper permissions (typically programs run by root have read+write access to the pipe) to send signals to the init program (PID 1).

The init manual page has, up until recently, simply stated that people wishing to understand how to send messages to init should read the init program's source code, but that is not usually practical.

Messages sent to the pipe to talk to init must have a special format. This format is defined as a C structure and the technical break-down is presented here:

/*

* Because of legacy interfaces, "runlevel" and "sleeptime"

* aren't in a separate struct in the union.

*

* The weird sizes are because init expects the whole

* struct to be 384 bytes.

*/

struct init_request {

int magic; /* Magic number */

int cmd; /* What kind of request */

int runlevel; /* Runlevel to change to */

int sleeptime; /* Time between TERM and KILL */

union {

struct init_request_bsd bsd;

char data[368];

} i; };

Let's go through the init_request structure one line at a time. The first variable, the "magic" number must be of the value 0x03091969. The init program then knows that only programs with root access which send this magic number are authorized to communicate with init.

The cmd variable is a value in the range of 0-8 (currently). This cmd variable tells init what we want it to do. Here are the possible options:

1 - Set the current runlevel, specified by the runlevel variable.

2 - The power will fail soon (probably low battery) prepare to shutdown.

3 - The power is failing, do shutdown immediately.

4 - The power is okay, cancel shutdown.

6 - Set an environment variable to a value to be specified in

the data variable of this structure.

Other cmd options may be added to init later. For example, command values 0, 5 and 7 are defined but currently not implemented.

The runlevel variable will specify the runlevel to switch to (0-6).

The sleeptime variable is to be used when we want to tell init to change the time spent waiting between sending SIGTERM and SIGKILL during the shutdown process. Changing this at run time is not yet implemented.

The data variable (in the union) can be used to pass misc data which init might need to process our request. For example, when setting environment variables.

When setting an environment variable through init's /dev/initctl pipe, the data variable should have the format VARIABLE=VALUE. The string should be terminated with a NULL character.

## EXAMPLES
The following C code example shows how to send a set environment variable request to the init process using the /dev/initctl pipe. This example is simplified and skips the error checking. A more comlpete example can be found in the shutdown.c program's init_setnv() function.

```
struct init_request     request;           /* structure defined above */
int                     fd;                /* file descriptor for pipe */
memset(&request, 0, sizeof(request));      /* initialize structure */
request.magic = 0x03091969;                /* magic number required */
request.cmd = 6;                           /* 6 is to set a variable */
sprintf(request.data, "VARIABLE=VALUE");   /* set VAR to VALUE in init */
if ((fd = open(INIT_FIFO, O_WRONLY)) >= 0) /* open pipe for writing */
{

    size_t s  = sizeof(request);           /* size of structure to write */

    void *ptr = &request;                  /* temporary pointer */

    write(fd, ptr, s);                     /* send structure to the pipe */

    close(fd);                             /* close the pipe when done */
}
```

## NOTES
Usually the /dev/initctl pipe would only be used by low-level programs to request a power-related shutdown or change the runlevel, like telinit would do. Most of the time there is no need to talk to init directly, but this gives us an extenable approach so init can be taught how to learn more commands.

The commands passed through the /dev/initctl pipe must be sent in a specific binary format and be of a specific length. Larger data structures or ones not using the proper format will be ignored. Typically, only root has the ability to write to the initctl pipe for security reasons.

The /dev/initctl pipe can be closed by sending init (PID 1) the SIGUSR2 signal. This closes the pipe and leaves it closed. This may be useful for making sure init is not keeping any files open. However, when the pipe is closed, init no longer receives signals, such as those sent by shutdown or telinit. In other words if we close the pipe, init cannot change its runlevel directly. The pipe may be re-opened by sending init (PID 1) the SIGUSR1 signal.

If the /dev/initctl pipe is closed then it may still be possible to bring down the system using the shutdown command's -n flag, but this is not always clean and not recommended.

## FILES
/dev/initctl /sbin/init

## AUTHOR
Jesse Smith <jsmith@resonatingmedia.com>

## SEE ALSO
init(8)


initscript

title: initscript(5)

summary: script that executes inittab commands.

text:
# initscript(5)

## NAME
initscript - script that executes inittab commands.

## SYNOPSIS
/bin/sh /etc/initscript id runlevels action process

## DESCRIPTION
When the shell script /etc/initscript is present, init will use it to execute the commands from inittab. This script can be used to set things like ulimit and umask default values for every process.

## EXAMPLES
This is a sample initscript, which might be installed on your system as /etc/initscript.sample.

```
#
# initscript   Executed by init(8) for every program it
#              wants to spawn like this:
#
#              /bin/sh /etc/initscript <id> <level> <action> <process>
#

  # Set umask to safe level, and enable core dumps.

  umask 022

  ulimit -c 2097151

  PATH=/bin:/sbin:/usr/bin:/usr/sbin

  export PATH

  # Increase the hard file descriptor limit for all processes

  # to 8192.  The soft limit is still 1024, but any unprivileged

  # process can increase its soft limit up to the hard limit

  # with "ulimit -Sn xxx" (needs a 2.2.13 or later Linux kernel).

  ulimit -Hn 8192

  # Execute the program.

  eval exec "$4"
```

## NOTES
This script is not meant as startup script for daemons or services. It has nothing to do with a rc.local style script. It's just a handler for things executed from /etc/inittab. Experimenting with this can make your system un(re)bootable.

## FILES
/etc/inittab, /etc/initscript.

## AUTHOR
Miquel van Smoorenburg ,<miquels@cistron.nl>

## SEE ALSO
inittab(5), init(8).


inittab

title: inittab(5)

text:
# inittab(5)

## NAME
inittab - format of the inittab file used by the sysv-compatible init process

## DESCRIPTION
The inittab file describes which processes are started at bootup and during normal operation (e.g. /etc/init.d/boot, /etc/init.d/rc, gettys...). Init(8) distinguishes multiple runlevels, each of which can have its own set of processes that are started. Valid runlevels are 0-6 plus A, B, and C for ondemand entries. An entry in the inittab file has the following format:

id:runlevels:action:process

Lines beginning with `#' are ignored. id

is a unique sequence of 1-4 characters which identifies an entry in inittab (for versions of sysvinit compiled with the old libc5 (< 5.2.18) or a.out libraries the limit is 2 characters). Note: traditionally, for getty and other login processes, the value of the id field is kept the same as the suffix of the corresponding tty, e.g. 1 for tty1. Some ancient login accounting programs might expect this, though I can't think of any.

runlevels

lists the runlevels for which the specified action should be taken.

action

describes which action should be taken.

process

specifies the process to be executed. If the process field starts with a `+' character, init will not do utmp and wtmp accounting for that process. This is needed for gettys that insist on doing their own utmp/wtmp housekeeping. This is also a historic bug. The length of this field is limited to 127 characters.

The runlevels field may contain multiple characters for different runlevels. For example, 123 specifies that the process should be started in runlevels 1, 2, and 3. The runlevels for ondemand entries may contain an A, B, or C. The runlevels field of sysinit, boot, and bootwait entries are ignored.

When the system runlevel is changed, any running processes that are not specified for the new runlevel are killed, first with SIGTERM, then with SIGKILL.

Valid actions for the action field are:

respawn

The process will be restarted whenever it terminates (e.g. getty).

wait

The process will be started once when the specified runlevel is entered and init will wait for its termination.

once

The process will be executed once when the specified runlevel is entered.

boot

The process will be executed during system boot. The runlevels field is ignored.

bootwait

The process will be executed during system boot, while init waits for its termination (e.g. /etc/rc). The runlevels field is ignored.

off

This does nothing.

ondemand

A process marked with an ondemand runlevel will be executed whenever the specified ondemand runlevel is called. However, no runlevel change will occur (ondemand runlevels are `a', `b', and `c').

initdefault

An initdefault entry specifies the runlevel which should be entered after system boot. If none exists, init will ask for a runlevel on the console. The process field is ignored.

sysinit

The process will be executed during system boot. It will be executed before any boot or bootwait entries. The runlevels field is ignored.

powerwait

The process will be executed when the power goes down. Init is usually informed about this by a process talking to a UPS connected to the computer. Init will wait for the process to finish before continuing.

powerfail

As for powerwait, except that init does not wait for the process's completion.

powerokwait

This process will be executed as soon as init is informed that the power has been restored.

powerfailnow

This process will be executed when init is told that the battery of the external UPS is almost empty and the power is failing (provided that the external UPS and the monitoring process are able to detect this condition).

ctrlaltdel

The process will be executed when init receives the SIGINT signal. This means that someone on the system console has pressed the CTRL-ALT-DEL key combination. Typically one wants to execute some sort of shutdown either to get into single-user level or to reboot the machine.

kbrequest

The process will be executed when init receives a signal from the keyboard handler that a special key combination was pressed on the console keyboard. The documentation for this function is not complete yet; more documentation can be found in the kbd-x.xx packages (most recent was kbd-0.94 at the time of this writing). Basically you want to map some keyboard combination to the "KeyboardSignal" action. For example, to map Alt-Uparrow for this purpose use the following in your keymaps file:

alt keycode 103 = KeyboardSignal

## EXAMPLES
This is an example of a inittab which resembles the old Linux inittab:

```
# inittab for linux
id:1:initdefault:
rc::bootwait:/etc/rc
1:1:respawn:/etc/getty 9600 tty1
2:1:respawn:/etc/getty 9600 tty2
3:1:respawn:/etc/getty 9600 tty3
4:1:respawn:/etc/getty 9600 tty4
```

This inittab file executes /etc/rc during boot and starts gettys on tty1-tty4. A more elaborate inittab with different runlevels (see the comments inside):

```
# Level to run in
id:2:initdefault:
# Boot-time system configuration/initialization script.
si::sysinit:/etc/init.d/rcS
# What to do in single-user mode.
~:S:wait:/sbin/sulogin
# /etc/init.d executes the S and K scripts upon change
# of runlevel.
#
# Runlevel 0 is halt.
# Runlevel 1 is single-user.
# Runlevels 2-5 are multi-user.
# Runlevel 6 is reboot.
l0:0:wait:/etc/init.d/rc 0
l1:1:wait:/etc/init.d/rc 1
l2:2:wait:/etc/init.d/rc 2
l3:3:wait:/etc/init.d/rc 3
l4:4:wait:/etc/init.d/rc 4
l5:5:wait:/etc/init.d/rc 5
l6:6:wait:/etc/init.d/rc 6
# What to do at the "3 finger salute".
ca::ctrlaltdel:/sbin/shutdown -t1 -h now
# Runlevel 2,3: getty on virtual consoles
# Runlevel   3: getty on terminal (ttyS0) and modem (ttyS1)
1:23:respawn:/sbin/getty tty1 VC linux
2:23:respawn:/sbin/getty tty2 VC linux
3:23:respawn:/sbin/getty tty3 VC linux
4:23:respawn:/sbin/getty tty4 VC linux
S0:3:respawn:/sbin/getty -L 9600 ttyS0 vt320
S1:3:respawn:/sbin/mgetty -x0 -D ttyS1
```

## FILES
/etc/inittab

## AUTHOR
Init was written by Miquel van Smoorenburg (miquels@cistron.nl). This manual page was written by Sebastian Lederer (lederer@francium.informatik.uni-bonn.de) and modified by Michael Haardt (u31b3hs@pool.informatik.rwth-aachen.de).

## SEE ALSO
init(8), telinit(8)


title: tac_plus.conf(5)

summary: tacacs+ daemon configuration file

text:
# tac_plus.conf(5)

## NAME
tac_plus.conf - tacacs+ daemon configuration file

## DESCRIPTION
This page is a work in progress.

tac_plus.conf contains configuration information for the tac_plus (tacacs+) daemon.

Each line contains either one of the directives documented below, white-space (blanks or tabs), or a comment.

Syntax enclosed in angle brackets (<>) below, refer to syntax documented elsewhere in this manual page.

## TOP-LEVEL DIRECTIVES
\#

Comments begin with a '#' character and extend to the end of the line. Comments may appear anywhere in the configuration file. To disable the special meaning of the '#' character, enclose the string containing it in double quotes ("#").

accounting

Only one configurable account parameter exists, the destination. All accounting records are either written to a file, syslog(3) at priority info, or both.

```
    accounting syslog;

    accounting file = <filename>
```

The default filename is /var/log/tac_plus.acct.

Since accounting requests occur (and are serviced) asynchronously, it is necessary to lock the accounting file so that two writers do not simultaneously write to it. The daemon uses fcntl(2) to lock the file. Although fcntl(2) locking over NFS is supported on some implementations, it is notoriously unreliable. Even if it is reliable, locking is likely to be extremely inefficient over NFS. The file is best located on a local file system.

acl

If compiled with acl support (--enable-acls), Access Control Lists can be defined to limit user's (or group's) login and/or enable access by daemon client IP address or hostname. An acl is referenced by its name, but must be defined before it can be referenced. The acl is a series of permit or deny statements applied to the source IP address that the client used to connected to the daemon. The first <regex> that matches ends the evaluation and the result is the permit or deny on left. If no entry of the acl matches a given address, the result is an implicit deny.

```
    acl = <name> {

        <permission> = <regex>

        # deny 66.1.255/24, allow all else in 66.1/16

        deny = ^66\.1\.255\.

        permit = ^66\.1\.

        # implicit deny (ie: anything else)

    }
```

Briefly, if a company had all their loopback interfaces numbered from 66.1/16 (and thus all the tacacs clients are within 66.1/16), this acl might be used to dis-allow a user to login to (or enable on) any router whose loopback interface is in 66.1.255/24.

Note: because acls match against the daemon client's source IP address, the client should be configured to use a stable source such as a loopback interface. For example:

```
    ip tacacs-server source-interface loopback 0
```

default authentication

By default, authentication fails for users that do not appear in the configuration file. This overrides that behavior, thus permitting all authentication requests for such users.

```
    default authentication = file <filename>
```

Such users will be authentication via the <user> "DEFAULT".

Also see "user = DEFAULT", <default service>, and <default attribute>.

group

Analogous to a <user> and accepting the same syntax, a group provides a template of which a <user> or another group can be a member.

```
    group = <name> {

        <user_decl>

    }
```

A group may be recursive; that is a group may be a member of one other group (which may be a member of yet another group, and so on).

host

The host clause allows the configuration values noted below to be set for the client named by IP address. If tac_plus is started with the -L option, the name can also be name as resolved from the address with the gethostbyaddr(3) system call, which may be the FQDN (Fully Qualified Domain Name) if DNS is used. It is recommended that the IP address be used, since the resolver can be slow to timeout when network faults exist.

```
    host = <IP address> {
	key = <string>
	prompt = <string>
	enable = <password_spec>

    }
```

key specifics the packet encryption <key> for this host.

prompt specifies the username prompt that will be presented to a user.

key

Specifies an encryption key used to encrypt packets between the daemon and clients. This key must match the key configured on the clients. key = <string>

The double quotes are only necessary if your key contains white-space, key-words, or special characters.

Note: encryption is highly recommended.

logging

Specifies the syslog(3) facility used. By default, logs are posted to the daemon facility.

```
    logging = <syslog_fac>
```

user

Define a user whose username is <name>.

```
    user = <name> {

        [ <default service> ]

        <user_attr>

        <svc>

    }
```

Note: seventeen special usernames exist: "DEFAULT", "$enable$", and "$enabN$" (where N is a privilege level number, normally in the range 0-15 on a Cisco). The "$enable$" user is for backward compatibility with previous versions of tacacs that is queried for privilege level 15 in addition to "$enab15$".

Also see the "priv-lvl" AV pair in the "AV Pairs" section below and the <default authentication> directive.

service

```
    user = <string> {

        [ default service = <permission> ]

        <user_attr>*

        <svc>*

    }
```

Also see the <default service> directive.

## ADDITIONAL DIRECTIVE SYNTAX
attr_value_pair

Specify an AV (Attribute Value) pair. The "optional" keyword specifies that the AV pair is optional.

```
    [ optional ] <string> = <string>
```

Optional AV pairs are only sent to the client if it requests them. That is, the client must have included the given AV pair as a mandatory or optional pair in the request.

Some clients react incorrectly and negatively to receiving AV pairs that it did not solicit. Optional AV pairs should be ignored if they are not recognized or not supported in any given context.

Also see the "Configuring Authorization" and "AV Pairs" sections below.

cmd_auth

Specify command authorization. For command authorization, the device should expand all abbreviated commands to their full names and compress adjacent white-space. For example, when the command "config t" is entered it will be expanded to "configure terminal".

```
    cmd = <string> {

        <cmd-match>

    }
```

cmd-match

Specify a command argument match.

```
    <permission> <regex>

    <permission> <regex>
	...

    <permission>
```

The <regex> matches arguments of the command <string>. For example, to allow show diag but no other show commands:

```
    cmd = show {

        permit diag

        deny

    }
```

The end of the <cmd-match> has an implicit <permission> determined by <default service>. So, if the 'deny' had been omitted in the example above, the result of the authorization would be the value of <default service>.

Note: 'cmd-arg' should never appear in a configuration file. It is used internally by the daemon to construct a string which is then matched against the regular expressions which appear in a cmd clause in the configuration file.

Note: when a command has multiple arguments, they may be entered in many different permutations. It can be cumbersome to create regular expressions which will reliably authorize commands under these conditions. Administrators may wish to consider other methods of performing authorization.

default service

Specifies the default <permission> for service authorization.

```
    default service = <permission>
```

If omitted, the default is 'deny'.

Note: if used, <default service> must precede all other <svc> directives in a <user> clause.

default attribute

Specifies the default attribute <permission> for service authorization.

```
    default attribute = <permission>
```

Note: if used, <default attribute> must precede all other <svc_attr> directives in a <svc> clause.

des_string

Represents the one-way encryption of a password <string>. For example, a password might encrypt to the string 0AmUKnIT2gheo. DES is the encryption historically used in Unix passwd(5) files. The crypt() function of the system's libcrypt is used to perform the encryption. The libcrypt of modern Unicies tend to support additional encryption algorithms and thus so would tac_plus. See the system's crypt manual page. To utilize another format, use the des keyword followed by the crypt in the format as described in the manpage. Typically it will have a "$1" prefix for MD5, "$2" for blowfish, and so on.

tac_pwd(8) is a utility supplied with tac_plus to assist in performing this encryption.

expires

Causes the <user>'s password to become invalid, starting on the specified expiration date.

```
    expires "May 23 2005"
```

A expiry warning message is sent to the user at login time, starting at 14 days before the expiration date.

If the <user>'s <login> <password_spec> is "file", the "expires" field of the configuration file is not consulted. Instead, the daemon looks at the the "shell" field of the password file entry for a valid expiration date.

If Solaris shadow password files are used for authentication, the "expires" field of the configuration file is not consulted. The expiry field from the shadow password file (if it exists) is used as the expiration date.

Case is not significant.

filename

A <string> specifying a file located in the filesystem. While the daemon does change directories to / (root) when it starts, it is best to specify files by their FQPN (Fully Qualified Path Name). That is, a path that begins with /. For example, /var/log/file rather than the relative path var/log/file.

IP address

A <string> representing an IPv4 address in dotted-quad notation. For example:

```
    192.168.1.1
```

name

A <string> by which to refer to a configuration element, such as an <acl> or a <group>. In general, a <name> must be defined before it can be referenced. For example, before a <user> can be a specified as a member of a <group>, the <group> has to be defined.

password_spec

There are five authentication mechanisms available: no password, cleartext, DES, PAM, a file in passwd(5) format, and skey.

```
    file <filename>

    cleartext <string>

    des <des_string>

    PAM

    skey

    nopassword
```

skey is an OTP (One Time Password) facility. The daemon must be built with skey (--enable-skey) support.

PAM (Pluggable Authentication Modules framework) is an authentication mechanism (and much more) capable of various types of authentication methods that are chosen by a configuration file. The PAM service name is the name of tac_plus executable, normally "tac_plus". PAM can be used only for login authentication, it is not implemented for enable authorization, and does not support OTP-like challenge system (ie: no additional prompting). The daemon must be built with PAM support, which is included by default if libpam is found.

Note: some cases of <password_spec> do not accept all of these mechanisms.

permission

Specifies that some match (for example a <service> or <cmd-match>) is to be allowed or denied.

```
    (permit | deny)
```

proto

A protocol is a subset of a service. Typical NAS supported values are atalk, bap, bridging, ccp, cdp, deccp, ip, ipx, lat, lcp, multilink, nbf, osicp, pad, rlogin, telnet, tn3270, vines, vpdn, xns, xremote, and unknown. Note that 'protocol' is actually an AV pair.

string

A series of characters, not including white-space or tac_plus key-words or special characters (ie: A-Za-z0-9_). To include any of those exceptions, enclose the string in double quotes ("this has whitespace").

svc

XXX:

```
    <svc_auth> | <cmd_auth>
```

svc_auth

XXX: service = ( arap | connection | exec | ppp protocol = <proto> | shell | slip | system | tty-daemon | <client defined> ) { [ <default attribute> ]

<attr_value_pair>*

} The service AV pair is required.

syslog_fac

syslog(3) normally has 16 well-known channels, called facilities. syslogd(8) can be configured to direct each of these facilities to different files. The facilities are named: auth, cron, daemon, local[0-7], lpr, mail, news, syslog, user, and uucp.

user_attr

XXX:

```
    user = bart {

        arap = cleartext "arap password"

        chap = cleartext "chap password"

        enable = <password_spec>

        pap  = cleartext "inbound pap password"

        opap = cleartext "outbound pap password"

        pap  = des <des_string>

        pap  = file <filename>

        pap  = PAM

        login = <password_spec>

        global = cleartext "outbound pap password"

    }
```

global specifies the authentication method for all services. login applies to normal logins (exec). arap, chap, pap, and opap (outbound PAP) service passwords may be defined separately.

NOTE: a global user password cannot be used for outbound PAP. This is because outbound PAP is implemented by sending the password from the daemon to the client. This is a security issue if the <key> is ever compromised.

enable specifies the enable password. The <password_spec> may only be of type cleartext, des, nopassword or file. If the daemon was compiled with per-user enable support (--enable-uenable), the host enable password will be evaluated iff the user does not have a personal enable password.

login name member - can only be 1 default service = permit expires "May 23 2005"

arap = cleartext "Fred's arap secret"

chap = cleartext "Fred's chap secret" acl = <string> enableacl = <string>

In the case of recursion, the first match is returned. host enable is cleartext, des, nopassword or file only. arap chap expires May 23 2005 login member password user_attr := name = <string> |

login = <password_spec> |

member = <string> |

expires = <string> |

arap = cleartext <string> |

chap = cleartext <string> | #ifdef MSCHAP

ms-chap = cleartext <string> | #endif

pap = cleartext <string> |

pap = des <string> |

pap = file <filename> | #ifdef PAM

pap = PAM | #endif

opap = cleartext <string> |

global = cleartext <string> |

msg = <string>

before authorization = <string> |

after authorization = <string>

## CONFIGURING AUTHORIZATION
Authorizing a single session can result in multiple requests being sent to the daemon. For example, to authorize a dialin ppp user for IP, the following authorization requests would be made from the client:

1)

An initial authorization request to startup ppp from the exec, using the AV pairs service=ppp protocol=ip, will be made (Note: this initial request will be omitted if you are autoselecting ppp, since username will not be known yet). This request is really done to find the address for dumb PPP (or SLIP) clients who cannot do address negotiation. Instead, they expect you to tell them what address to use before PPP starts up, via a text message.

2)

Next, an authorization request is made from the PPP subsystem to see if ppp's LCP layer is authorized. LCP parameters can be set at this time (e.g. callback). This request contains the AV pairs service=ppp protocol=lcp.

3)

Next an authorization request to startup ppp's IPCP layer is made using the AV pairs service=ppp protocol=ipcp. Any parameters returned by the daemon are cached.

4)

Next, during PPP's address negotiation phase, each time the remote peer requests a specific address, if that address isn't in the cache obtained in step 3, a new authorization request is made to see if the peers requested address is allowable. This step can be repeated multiple times until both sides agree on the remote peer's address or until the NAS (or client) decide they're never going to agree and they shut down PPP instead.

As you can see from the above, a program which plans to handle authorization must be able to handle a variety of requests and respond appropriately.

Authorization must be configured on both the client and the daemon to operate correctly. By default, the client will allow everything until configured to make authorization requests to the daemon.

With the daemon, the opposite is true; by default, the daemon will deny authorization of anything that isn't explicitly permitted.

Authorization allows the daemon to deny commands and services outright, or to modify commands and services on a per-user basis. Authorization on the daemon is divided into two separate parts: commands and services.

Authorizing:

commands

Exec commands are those commands which are typed at a Cisco exec prompt. When authorization is requested by the NAS, the entire command is sent to the daemon for authorization. Command authorization is configured by specifying a list of <regex>s to match command arguments and an action which is a <permission>.

The following permits user Fred to run these commands:

```
    telnet 131.108.13.<any number> and

    telnet 128.<any number>.12.3 and

    show <anything>
```

All other commands are denied (by default).

```
    user=fred {

        cmd = telnet {

            # permit specified telnets

            permit 131\.108\.13\.[0-9]+

            permit 128\.[0-9]+\.12\.3

        }

        cmd = show {

            # permit show commands

            permit .*

        }

    }
```

The command and arguments which the user types are matched to the regular expressions specified in the configuration file (in order of appearance). The first successful match performs the associated action (<permission>). If there is no match, the command is denied by default.

Also see the <default authentication>, <default authorization>, <default attribute>, and <default service> directives.

## AUTHORIZATION SCRIPTS
There are some limitations to the authorization that can be done using a configuration file. One solution is to arrange for the daemon to call user-supplied programs to control authorization. These "callouts" permit almost complete control over authorization, allowing you to read all the fields in the authorization packet sent by the client, including all its AV pairs, and to set authorization status and send a new set of AV pairs to the client in response.

Pre and post authorization programs are invoked by handing the command line to the Bourne shell. On most Unix systems, if the shell doesn't find the specified program it returns a status of one, which denies authorization. However, at least one Unix system (BSDI) returns a status code of 2 under these circumstances, which will permit authorization, and probably isn't what you intended.

Note: if your program hangs, the authorization will time out and return an error on the client, and you'll tie up a process slot on the daemon host, eventually running out of resources. There is no special code to detect this in the daemon.

The daemon communicates with pre and post (before and after) authorization programs over a pair of pipes. Programs using the standard i/o library will use full buffering in these circumstances. This should not be a problem, since AV pairs will be read until end of file (EOF) is seen on input, and output will be flushed when they exit.

Fields from the authorization packet can be supplied to the programs as arguments on the command line by using the appropriate dollar-sign variables in the configuration file. These fields are:

```
    user    -- user name

    name    -- client/NAS name

    ip      -- client/NAS IP

    port    -- client/NAS port

    address -- user address (remote user location)

    priv    -- privilege level number (0-15)

    method  -- a digit (1-4)

    type    -- digit (1-4)

    service -- digit (1-7)

    status  -- (pass, fail, error, unknown)
```

Unrecognized variables will appear as the string "unknown".

AV pairs from the authorization packet are fed to the program's standard input, one per line. The program is expected to process the AV pairs and write them to its standard output, one per line. What happens then is determined by the exit status of the program.

Note: when AV pairs containing spaces are listed in the configuration file, you need to enclose them in double quotes so that they are parsed correctly. AV pairs which are returned via standard output do not need delimiters and so should not be enclosed in double quotes.

Note: unless special arrangements are made, the daemon will run as root and hence the programs it invokes will also run as root, which is a security weakness. It is strongly recommended that FQPNs are used when specifying programs to execute, and that the daemon is compiled with unprivileged user and group IDs (--with-userid and --with-groupid) so that the daemon is not running as root when calling these programs,

Calling scripts

before authorization

Specify a per-user program to be called before any other authorization attempt is made by using a "before" clause.

```
    user = auth1 {

        before authorization "/path/pre_authorize $user $port $address"

    }
```

The AV pairs sent from the NAS will be supplied to the program standard input, one pair per line.

If the program returns a status of 0, authorization is unconditionally permitted. No further processing is done on this request and no AV pairs are returned to the client.

If the program returns a status of 1, authorization is unconditionally denied. No further processing is done on this request and no AV pairs are returned to the client.

If the program returns a status of 2, authorization is permitted. The program is expected to modify the AV pairs that it receives on its standard input (or to create entirely new ones) and to write them, one per line, to its standard output. The new AV pairs will be sent to the client with a status of AUTHOR_STATUS_PASS_REPL. No further processing takes place on this request.

If the program returns a status of 3, authorization is denied, but all attributes returned by the program via stdout are returned to the client. Also, whatever the program returns on stderr is placed into the server-msg field and returned to the client.

Any other status value returned from the program will cause an error to be returned to the client.

Note: a status of 2 is not acceptable when doing command authorization.

after authorization

Specify a per-user program to be called after authorization processing has been performed by the default, but before the authorization status and AV pairs have been transmitted to the client, by using a "after" clause.

```
    group = auth1 {

        after authorization "/path/post_authorize $user $port $status"

    }
```

The AV pairs resulting from the authorization algorithm that the daemon proposes to return to the NAS, are supplied to the program on standard input, one AV pair per line, so they can be modified if required.

The program is expected to process the AV pairs and write them to its standard output, one per line. What happens then is determined by the exit status of the program:

If the program returns a status of 0, authorization continues as if the program had never been called. Use this if (for example) to just send mail when an authorization occurs, without otherwise affecting normal authorization.

If the program returns a status of 1, authorization is unconditionally denied. No AV pairs are returned to the NAS. No further authorization processing occurs on this request.

If the program returns a status of 2, authorization is permitted and any AV pairs returned from the program on its standard output are sent to the NAS in place of any AV pairs that the daemon may have constructed.

Any other value will cause an error to be returned to the NAS by the daemon.

Current attributes are:

```
    "unknown"

    "service"

    "start_time"

    "port"

    "elapsed_time"

    "status"

    "priv_level"

    "cmd"

    "protocol"

    "cmd-arg"

    "bytes_in"

    "bytes_out"

    "paks_in"

    "paks_out"

    "address"

    "task_id"

    "callback-dialstring"

    "nocallback-verify"

    "callback-line"

    "callback-rotary"
```

Also see the "AV Pairs" section below.

## AV PAIRS
AV (Attribute Value) pairs are text strings exchanged between the client and server of the form "attribute=value". The value may not appear in authorization request packets, indicating that it is null or unspecified. The equal sign ('=') means that this is a mandatory attribute. An asterisk ('*') may appear in place of the equal sign, indicating that it is an optional attribute which either the client or server may not understand or may ignore.

Optional attributes are preceded by the "optional" key-word in the configuration. For example:

```
    priv_lvl = 15

    optional allow-shell = true

    service=ppp

    protocol=ip

    addr*131.108.12.44
```

The following AV pairs specify which service is being authorized. They are typically accompanied by protocol AV pairs and other, additional pairs from the lists below.

service=arap

service=shell

for exec startup, and also for command authorizations. Requires:

```
    aaa authorization exec tacacs+
```

service=ppp

service=slip

service=system

not used.

service=raccess

Used for managing reverse telnet connections e.g.

```
    user = jim {

        login = cleartext lab

        service = raccess {

            port#1 = clientname1/tty2

            port#2 = clientname2/tty5

        }

    }
```

Requires IOS configuration

```
    aaa authorization reverse-access tacacs+
```

protocol=lcp

The lower layer of PPP, always brought up before IP, IPX, etc. is brought up.

protocol=ip

Used with service=ppp and service=slip to indicate which protocol layer is being authorized.

protocol=ipx

Used with service=ppp to indicate which protocol layer is being authorized.

protocol=atalk

with service=ppp or service=arap

protocol=vines

For vines over ppp.

protocol=ccp

Authorization of CCP. Compression Control Protocol). No other AV-pairs associated with this.

protocol=cdp

Authorization of CDP (Cisco Discovery Protocol). No other av-pairs associated with this.

protocol=multilink

Authorization of multilink PPP.

protocol=unknown

For undefined/unsupported conditions. Should not occur under normal circumstances.

Incomplete list of Cisco AV pairs. Other vendors may provide additional AV pairs specific to their products.

acl

For EXEC authorization this contains an access-class number (acl=2) which is applied to the line (tty) as the output access class. The specified access-list must be predefined. ARAP, EXEC.

addr

The IP address the remote host should be assigned when a slip or PPP/IP connection is made. For example: addr=1.2.3.4 SLIP, PPP/IP.

autocmd

During exec startup, this specifies an autocommand, like the autocommand option to the username configuration command. For example: autocmd="telnet foo.com" EXEC.

callback-line

The number of a TTY line to use for the callback. Used with service=arap, slip, ppp, or shell. Does not work for ISDN.

callback-rotary

The number of a rotary group (0 through 100) to use for the callback. Used with service=arap, slip, ppp, and shell. Does not work for ISDN.

cmd

If the value of cmd is NULL (cmd=), then this is an authorization request for starting an exec. If cmd is non-null, this is a command authorization request. It contains the name of the command being authorized. For example: cmd=telnet

EXEC.

cmd-arg

During command authorization, the name of the command is given by an accompanying "cmd=" AV pair, and each command argument is represented by a cmd-arg AV pair e.g. cmd-arg=archie.sura.net NOTE: 'cmd-arg' should never appear in a configuration file. It is used internally by the daemon to construct a string which is then matched against the regular expressions which appear in a cmd clause in the configuration file.

EXEC.

dns-servers

Identifies a primary or backup DNS server that can be requested by Microsoft PPP clients during IPCP negotiation. Used with service=ppp and protocol=ip.

gw-password

Specifies the password for the home gateway during L2F tunnel authentication. Used with service=ppp and protocol=vpdn.

idletime

Sets a value, in minutes, after which an IDLE session will be terminated. Does NOT work for PPP. EXEC, 11.1 onward.

inacl

This AV pair contains an IP or IPX input access list number for slip or PPP (inacl=2). The access list itself must be pre-configured on the Cisco box. Per-user access lists do not work with ISDN interfaces unless you also configure a virtual interface. After 11.2(5.1)F, you can also use the name of a predefined named access list, instead of a number, for the value of this attribute. Note: For IPX, inacl is only valid after 11.2(4)F.

PPP/IP/IPX.

inacl#<n>

This AV pair contains the definition of an input access list to be installed and applied to an interface for the duration of the current connection, e.g.

```
    inacl#1="permit ip any any precedence immediate"

    inacl#2="deny igrp 0.0.1.2 255.255.0.0 any"
```

Attributes are sorted numerically before they are applied. For IP, standard OR extended access list syntax may be used, but it is an error to mix the two within a given access-list.

For IPX, only extended access list syntax may be used.

PPP/IP/PPP/IPX, 11.2(4)F.

interface-config

Specifies user-specific AAA interface configuration information with Virtual Profiles. The information that follows the equal sign (=) can be any Cisco IOS interface configuration command.

ip-address

List of possible IP addresses, separated by spaces, that can be used for the end-point of a tunnel. Used with service=ppp and protocol=vpdn.

link-compression

Defines whether to turn on or turn off Stac compression over a PPP link. Valid values are:

```
	0	None
	1	Stac
	2	Stac Draft-9
	3	MS-Stac
```

load-threshold

This AV pair sets the load threshold at which an additional multilink link is added to the bundle (if load goes above) or deleted (if load goes below).

```
    service=ppp protocol=multilink {

        load-threshold=<n>

    }
```

The range of <n> is [1-255].

PPP/multilink - Multilink parameter, 11.3.

max-links

This AV pair restricts the number of multilink bundle links that a user can have.

```
    service=ppp protocol=multilink {

        max-links=<n>

    }
```

The range of <n> is [1-255].

PPP/multilink, 11.3.

nas-password

Specifies the password for the NAS during L2F tunnel authentication. Used with service=ppp and protocol=vpdn.

nocallback-verify

Indicates that no callback verification is required. The only valid value for this parameter is the digit one, i.e. nocallback-verify=1. Not valid for ISDN. ARAP/EXEC, 11.1 onward.

noescape

During exec startup, this specifies "noescape", like the noescape option to the username configuration command. Can have as its value the string "true" or "false". For example: noescape=true EXEC.

nohangup

During exec startup, this specifies "nohangup", like the nohangup option to the username configuration command. Can have as its value the string "true" or "false". For example: nohangup=true EXEC.

old-prompts

Allows the prompts in TACACS+ to appear identical to those of earlier systems (TACACS and Extended TACACS). This allows the upgrade from TACACS or Extended TACACS to TACACS+ to be transparent to users.

outacl

This AV pair contains an IP or IPX output access list number for SLIP. PPP/IP or PPP/IPX connections (outacl=4). The access list itself must be pre-configured. Per-user access lists do not work with ISDN interfaces unless you also configure a virtual interface. PPP/IPX is supported in 11.1 onward only. After 11.2(5.1)F, you can also use the name of a predefined named access list, as well as a number, for the value of this attribute. PPP/IP, PPP/IPX.

outacl#<n>

This AV pair contains an output access list definition to be installed and applied to an interface for the duration of the current connection.

```
    outacl#1="permit ip any any precedence immediate"

    outacl#2="deny igrp 0.0.9.10 255.255.0.0 any"
```

Attributes are sorted numerically before they are applied. For IP, standard OR extended access list syntax may be used, but it is an error to mix the two within a given access-list.

For IPX, only extended access list syntax may be used.

PPP/IP/PPP/IPX, 11.2(4)F.

pool-def#

Defines IP address pools on the NAS. Used with service=ppp and protocol=ip.

pool-timeout

In conjunction with pool-def, defines IP address pools on the NAS. During IPCP address negotiation, if an IP pool name is specified for a user (see the addr-pool attribute), a check is made that the named pool is defined on the NAS. If it is, the pool is consulted for an IP address.

ppp-vj-slot-compression

Instructs the Cisco router not to use slot compression when sending VJ-compressed packets over a PPP link.

priv-lvl

Specifies the current privilege level for command authorizations, a number from zero to 15. For example: priv_lvl=5. Note: in 10.3 this attribute was priv_lvl, i.e. it contained an underscore instead of a hyphen.

EXEC.

route

This AV pair specifies a temporary static route to be applied, which expunged once the connection terminates. The daemon side declaration is:

```
    service=ppp protocol=ip {

        route="<dst_addr> <mask> [ <gateway> ]"

    }
```

<dst_address>, <mask>, and <gateway> are <IP address>'s. If the gateway is omitted, the peer's address is assumed.

PPP/IP/SLIP, 11.1 onward.

route#<n>

Same as the "route" attribute, except that these are valid for IPX as well as IP, and they are numbered, allowing multiple routes to be applied. For example:

```
    route#1="3.0.0.0 255.0.0.0 1.2.3.4"

    route#2="4.0.0.0 255.0.0.0"
```

or, for IPX,

```
    route#1="4C000000 ff000000 30.12.3.4"

    route#2="5C000000 ff000000 30.12.3.5"
```

PPP/IP/IPX, 11.2(4)F.

routing

Equivalent to the /routing flag in slip and ppp commands. Can have as its value the string "true" or "false". SLIP/PPP/IP.

rte-ftr-in#

Specifies an input access list definition to be installed and applied to routing updates on the current interface for the duration of the current connection. Used with service=ppp protocol=ip or protocol=ipx.

rte-ftr-out#

Output version of rte-ftr-in#.

sap#<n>

This AV pair specifies static SAPs (Service Advertising Protocol) to be installed for the duration of a connection. For example:

```
    sap#1="4 CE1-LAB 1234.0000.0000.0001 451 4"

    sap#2="5 CE3-LAB 2345.0000.0000.0001 452 5"
```

The syntax of static saps is the same as that used by the IOS "ipx sap" command. Used with service=ppp protocol=ipx.

PPP/IPX, 11.2(4)F.

sap-fltr-in#<n>

This AV pair specifies an input SAP filter access list definition to be installed and applied to the current interface, for the duration of the current connection. Only Cisco extended access list syntax is legal (ipx input-sap-filter <number>). For example:

```
    sap-fltr-in#1="deny 6C01.0000.0000.0001"

    sap-fltr-in#2="permit -1"
```

Attributes are sorted numerically before being applied. Used with service=ppp protocol=ipx.

PPP/IPX, 11.2(4)F.

sap-fltr-out#<n>

This AV pair specifies an output sap filter access list definition to be installed and applied on the current interface, for the duration of the current connection. Only Cisco extended access list syntax is legal (ipx output-sap-filter <number>), e.g

```
    sap-fltr-out#1="deny 6C01.0000.0000.0001"

    sap-fltr-out#2="permit -1"
```

Attributes are sorted numerically before being applied. Used with service=ppp protocol=ipx.

PPP/IPX, 11.2(4)F.

source-ip

This specifies a single ip address that will be used as the source of all VPDN packets generated as part of the VPDN tunnel (see the equivalent source-ip keyword in the IOS vpdn outgoing command). PPP/VPDN, now deprecated, only existed in releases 11.2(1.4) thru 11.2(4.0.2).

timeout

Sets the time until an ARAP or exec session disconnects unconditionally (in minutes). For example: timeout=60 ARAP/EXEC, 11.0 onward.

tunnel-id

This AV pair specifies the username that will be used to authenticate the tunnel over which the individual user MID will be projected. This is analogous to the "NAS name" in the "vpdn outgoing" command. PPP/VPDN, 11.2 onward.

zonelist

An Appletalk zonelist for arap (ARAP) equivalent to the line configuration command "arap zonelist". For example: zonelist=5.

AV pairs reserved for future use (this list may be out-dated):

```
    ppp-vj-slot-compression

    link-compression

    asyncmap

    x25-addresses (PPP/VPDN)

    frame-relay (PPP/VPDN)
```

Note: this AV pair list is NOT complete and not all AV pairs are supported by all vendors. See the vendor's documentation. When a client (or server) receives a mandatory AV pair that it does not understand, the authorization FAILS!

Also see the tac_plus user guide. Some of the callback, appletalk, IPX, VPDN, PPP routing, and address pool related AV pairs found in the user guide have been omitted.

## ACCOUNTING AV PAIRS
bytes_in

The number of input bytes transferred during this connection.

bytes_out

The number of output bytes transferred during this connection.

cmd

The command the user executed.

data-rate

This AV pair has been renamed. See nas-rx-speed.

disc-cause

Specifies the reason a connection was taken off-line. The Disconnect-Cause attribute is sent in accounting stop records. This attribute also causes stop records to be generated without first generating start records if disconnected before authentication.

```
	1	User request
	2	Lost carrier
	3	Lost service
	4	Idle timeout
	5	Session timeout
	6	Admin reset
	7	Admin reboot
	8	Port error
	9	NAS error
	10	NAS request
	11	NAS reboot
	12	Port unneeded
	13	Port pre-empted
	14	Port suspended
	15	Service unavailable
	16	Callback
	17	User error
	18	Host request
```

disc-cause-ext

Extends the disc-cause attribute to support vendor-specific reasons that a connection was taken off-line.

```
	1000	Session timed out. This value applies to all session types.
	1002	Reason unknown.
	1004	Failure to authenticate calling-party number.
	1010	No carrier detected. This value applies to modem connections.
	1011	Loss of carrier. This value applies to modem connections.
	1012	Failure to detect modem result codes. This value applies to modem connections.
	1020	User terminates a session. This value applies to EXEC sessions.
	1021	Timeout waiting for user input. This value applies to all session types.
	1022	Disconnect due to exiting Telnet session. This value applies to EXEC sessions.
	1023	Could not switch to SLIP/PPP; the remote end has no IP address. This value applies to EXEC sessions.
	1024	Disconnect due to exiting raw TCP. This value applies to EXEC sessions.
	1025	Bad passwords. This value applies to EXEC sessions.
	1026	Raw TCP disabled. This value applies to EXEC sessions.
	1027	Control-C detected. This value applies to EXEC sessions.
	1028	EXEC process destroyed. This value applies to EXEC sessions.
	1040	PPP LCP negotiation timed out. This value applies to PPP sessions.
	1041	PPP LCP negotiation failed.
	1042	PPP PAP authentication failed.
	1043	PPP CHAP authentication failed.
	1044	PPP remote authentication failed.
	1045	PPP received a Terminate Request from remote end.
	1046	Upper layer requested that the session be closed.  This value applies to PPP sessions.
	1101	Session failed for security reasons. This value applies to all session types.
	1102	Session terminated due to callback. This value applies to all session types.
	1120	Call refused because the detected protocol is disabled. This value applies to all session types.
```

elapsed_time

The elapsed time in seconds for the action. Useful when the device does not keep real time.

event

Information included in the accounting packet that describes a state change in the router. Events described are accounting starting and accounting stopping.

mlp-links-max

Gives the count of links known to have been in a given multilink session at the time the accounting record is generated.

mlp-sess-id

Reports the identification number of the multilink bundle when the session closes. This attribute applies to sessions that are part of a multilink bundle. This attribute is sent in authentication-response packets.

nas-rx-speed

Specifies the average number of bits per second over the course of the connection's lifetime. This attribute is sent in accounting stop records.

nas-tx-speed

Reports the transmit speed negotiated by the two modems.

paks_in

The number of input packets transferred during this connection.

paks_out

The number of output packets transferred during this connection.

port

The port into which the user was logged.

pre-bytes-in

Records the number of input bytes before authentication. This attribute is sent in accounting stop records.

pre-bytes-out

Records the number of output bytes before authentication. This attribute is sent in accounting stop records.

pre-paks-in

Records the number of input packets before authentication. This attribute is sent in accounting stop records.

pre-paks-out

Records the number of output packets before authentication. This attribute is sent in accounting stop records as Pre-Output-Packets.

pre-session-time

Specifies the length of time, in seconds, from when a call first connects to when it completes authentication.

priv_level

The privilege level associated with the action.

protocol

The protocol associated with the action.

reason

Information included in the accounting packet that describes the event that caused a system change. Events described are system reload, system shutdown, or accounting reconfiguration (turned on or off).

service

The service the user used.

start_time

The time, in seconds since 12:00 a.m. January 1, 1970, that the action started. The clock must be configured to receive this information.

stop_time

The time, in seconds since 12:00 a.m. January 1, 1970, that the action stopped. The clock must be configured to receive this information.

task_id

Start and stop records for the same event must have matching (unique) task_id numbers.

timezone

The time zone abbreviation for all timestamps included in this packet.

xmit-rate

This AV pair has been renamed nas-tx-speed.

## EXAMPLE CLIENT CONFIGURATION
Example Cisco configuration for tacacs+:

```
    aaa new-model

    aaa authentication login default tacacs+ local

    aaa authentication enable default tacacs+ enable

    aaa authorization exec default tacacs+

    aaa accounting exec default start-stop tacacs+

    !

    username root privilege 15 password 0 <root's password>

    !

    tacacs-server key <your key here>

    tacacs-server host <ip_address>

    ip tacacs source-interface loopback0

    !

    enable secret 0 <enable password>
```

Note that the aaa command syntax varies slightly between some versions of Cisco IOS and CatOS (Catalyst OS) also varies.

Example Juniper configuration for tacacs+:

```
    system {

        authentication-order [ password tacplus ];

        tacplus-server {

            <ip_address> secret <your key here>;

            <ip_address> {

                secret <your key here>;

                timeout 90;

            }

        }

    }
```

Both of these examples are brief. See the vendor's documentation for a description of what these configuration commands specify and for additional commands and arguments.

WARNING: If not properly configured, it may not be possible to login to the device!

## EXAMPLE TAC_PLUS CONFIGURATION

```
key = "your key here"
accounting file = /var/log/tac.acct
# authentication users not appearing elsewhere via
# the file /etc/passwd
default authentication = file /etc/passwd
acl = dial_only {

    # All access routers are in 192.168/16, but except for

    # 192.168.0.1 all backbone router are in 198.168.0/24.

    # deny access to the backbone routers.

    permit = ^192\.168\.0\.1$

    deny   = ^192\.168\.0\.

    permit = ^192\.168\.
}
group = no_backbone {

    # permit an exec to start and permit all commands and

    # services by default

    default service = permit

    service = exec {

        # When an exec is started, its connection access list

        # will be 4. "acl" is quoted because it is a keyword.

        # It also has an autocmd

        "acl" = 4

        autocmd = "telnet duffhost"

    }

    # group will only be allowed to login on NASes

    acl = dial_only
}
group = admin {

    # group members who don't have their own login password will be

    # looked up in /etc/passwd

    login = file /etc/passwd

    # group members who have no expiry date set will use this one

    expires = "Jan 1 1997"

    # deny access to backbone routers

    acl = dial_only
}
user = DEFAULT {

    service = ppp protocol = ip {

        addr-pool=foobar

    }
}
user = homer {

    default service = permit

    member = no_backbone
}
user = fred {

    login = des mEX027bHtzTlQ

    name = "Fred Flintstone"

    member = admin

    expires = "May 23 2005"

    arap = cleartext "Fred's arap secret"

    chap = cleartext "Fred's chap secret"

    service = exec {

        # When Fred starts an exec, his connection access

        # list is 5

        "acl" = 5

        # We require this autocmd to be done at startup

        autocmd = "telnet foo"

    }

    # All commands except show system are denied for Fred

    cmd = show {

        # Fred can run the following show command

        permit system

        deny .*

    }

    service = ppp protocol = ip {

        # Fred can run ip over ppp only if he uses one

        # of the following mandatory addresses. If he

        # supplies no address, the first one here will

        # be mandated

        addr=131.108.12.11

        addr=131.108.12.12

        addr=131.108.12.13

        addr=131.108.12.14

        # Fred's mandatory input access list number is 101

        inacl=101

        # We will suggest an output access list of 102, but the NAS may

        # choose to ignore or override it

        optional outacl=102

    }

    service = slip {

        # Fred can run slip. When he does, he will have to use

        # these mandatory access lists

        inacl=101

        outacl=102

    }
}
user = wilma {

    # Wilma has no password of her own, but she's a group member so

    # she'll use the group password if there is one. Same for her

    # password expiry date

    member = admin
}
```

## FILES
/etc/tac_plus.conf

Configuration file.

/var/log/tac_plus.acct

The default accounting file.

/var/log/tac_plus.log

The default log file.

## SEE ALSO
gethostbyaddr(3), passwd(5), regexp(3), tac_plus(8), tac_pwd(8)

Also see the tac_plus User Guide (user_guide) that came with the distribution. The user guide does not cover all the modifications to the original Cisco version nor does this manual page cover everything that is in the user guide (callback configuration, for example).

## AUTHOR
The tac_plus (tacacs+) developer's kit is a product of Cisco Systems. Made available at no cost and with no warranty of any kind. See the file COPYING and source files that came with the distribution for specifics.

## HISTORY
This manual page was adapted from code inspection and Cisco's tac_plus user guide.

## BUGS
This manual page is incomplete.


saveconfig.json

package: target-restore

title: saveconfig.json(5)

text:
# saveconfig.json(5)

## NAME
saveconfig.json - Saved configuration file for rtslib-fb and LIO kernel target

## DESCRIPTION
/etc/target/saveconfig.json is the default location for storing the configuration of the Linux kernel target, also known as LIO. Since the target is in the kernel, tools like targetctl or targetcli must be used to save and restore the configuration across reboots.

Generating or modifying this file by hand, or with other tools, is also supported. This fills a gap for users whose needs are not met by the targetcli configuration shell, who cannot use the rtslib Python library, and yet also wish to avoid directly manipulating LIO's configfs interface.

## OVERVIEW
The configuration file is in the "json" text format, which is both human- and machine-readable. Its format is very closely modeled on the layout and terminology that LIO uses. Attributes may be string, boolean, or numeric values. All sizes are expressed in bytes.

## LAYOUT

### TOP LEVEL SUMMARY
storage_objects describes mappings of resources on the local machine that can be used to emulate block devices.

fabric_modules describes settings for LIO fabrics -- the hardware or software protocols that transport SCSI commands -- such as iSCSI or Fibre Channel over Ethernet (FCoE).

targets describes the SCSI target endpoints that export storage objects over a fabric.

### storage_objects
All storage objects must contain name and plugin values. Each name must be unique for all storage objects of its plugin type.

plugin must be one of: fileio, block, pscsi, or ramdisk.

Objects with plugin value of fileio must also contain dev, which is the full path to the file that is backing the storage object. Optional fileio attributes are wwn (string), write_back (boolean), and size (number). If the file given in dev does not exist, then size must be present, and a backing file of that size will be created.

Objects with plugin value of block must also contain dev, which is the full path to the block device that is backing the storage object. Optional block attributes are wwn (string), write_back (boolean), and readonly (boolean).

Objects with plugin value of pscsi must also contain dev, which is the full path to the SCSI device that is backing the storage object. There are no optional attributes.

Objects with plugin value of ramdisk must also contain size (number), which is the size in bytes of the ramdisk. Optional ramdisk attributes are wwn (string), and nullio (boolean).

All storage object definitions may also contain an attributes object. This contains LIO attribute values, all of which are also optional. Please see LIO documentation for more information on these.

### fabric_modules
This section is limited to setting discovery authentication settings for fabrics that support it (currently just iscsi). Objects here should contain name (e.g. "iscsi"), userid, password, mutual_userid, and mutual_password string values.

### targets
Target configuration is modeled on iSCSI, in which a named target can contain multiple sub-configurations called Target Port Groups (TPGs). LIO follows this model for describing configuration even for fabrics that do not support TPGs.

Objects in targets contain just three attributes: wwn is the world-wide name the target has been given. This may start with "iqn", or "naa", for example. fabric is the name of the fabric module this target is exported over. Allowed values for this depend on the system configuration, but examples include "iscsi", "loopback", and "tcm_fc". tpgs is a list of objects describing 1 or more TPGs, described below.

### tpgs
TPG object attributes are all optional. Values not supplied will be set to default values. tag (number) allows the tpg tag to be specified. enable (bool, default to true) allows the TPG to be disabled or enabled. luns, portals, and node_acls contain further lists of objects, descibed below. Finally, userid, password, mutual_userid, and mutual_password allow main-phase authentication values to be set for fabrics (like iSCSI) that support TPG-level authentication. (Please see targetcli(8) for details on TPG versus ACL-based authentication.) Finally, TPGs can also contain optional attributes and parameters lists, see LIO documentation for more information.

### luns
This list of objects maps storage objects to the TPG. index is a TPG-unique number for the assignment, which may be used as the LU number for fabrics that do not support ACL mappings. storage_object is a string linking back to a storage object, of the format "/backstores/<plugin>/<name>", where <plugin> and <name> correspond to a storage object defined under storage_objects.

### portals
Portals describe connection endpoints for iSCSI targets. Required values are ip_address (string) and port (number). iser (boolean) is an optional value to enable iSER. offload (boolean) is an optional value to enable hardware offload.

### node_acls
This contains information about explicit initiator LUN mappings. node_wwn (string) must be present. Authentication may also be set on a per-ACL basis with userid, password, mutual_userid, and mutual_password, similar to TPGs. mapped_luns is a list of mapped luns, described below. Finally, node_acls can contain an optional attributes list.

### mapped_luns
Objects in mapped_luns contain three required attributes. write_protect (boolean) sets the write-protect status of the mapped LUN. tpg_lun (number) corresponds to an existing entry in the TPG's luns list. index is the LU number that the mapped LUN will claim.

## EXAMPLE CONFIGURATION
Since tools generate this file, one good way to understand its format is to use a tool like targetcli to configure a target, then run saveconfig, and view the resulting json file.

## SEE ALSO
targetcli(8), targetctl(8)

## FILES
/etc/target/saveconfig.json

## AUTHOR
Man page written by Andy Grover <agrover@redhat.com>.

## REPORTING BUGS
Report bugs via <targetcli-fb-devel@lists.fedorahosted.org>

or <https://github.com/open-iscsi/rtslib-fb/issues>