ocserv

title: ocserv(8)

summary: OpenConnect VPN server

text:
# ocserv(8)

## NAME
ocserv - OpenConnect VPN server

## SYNOPSIS
ocserv options -c [config]

OpenConnect VPN server (ocserv) is a VPN server compatible with the OpenConnect VPN client. It follows the AnyConnect VPN protocol which is used by several CISCO routers.

## DESCRIPTION
This a standalone server that reads a configuration file (see below for more details), and waits for client connections. Log messages are redirected to daemon facility.

The server maintains two connections/channels with the client. The main VPN channel is established over TCP, HTTP and TLS. This is the control channel as well as the backup data channel. After its establishment a UDP channel using DTLS is initiated which serves as the main data channel. If the UDP channel fails to establish or is temporarily unavailable the backup channel over TCP/TLS is being used.

This server supports multiple authentication methods, including PAM and certificate authentication. Authenticated users are assigned an unprivileged worker process and obtain a networking (tun) device and an IP from a configurable pool of addresses.

Once authenticated, the server provides the client with an IP address and a list of routes that it may access. In order to allow high-speed transfers the server does not process or filter packets. It is expected that the server has or will set up any required routes or firewall rules.

It is possible to separate users into groups, which are either present on their certificate, or presented on login for the user to choose. That way a user may take advantage of the different settings that may apply per group. See the comments on the configuration file for more information.

It is also possible to run hostname-based virtual servers which could support different authentication methods. When multiple virtual servers are present clients are distinguished by the advertised server name over TLS (SNI). Clients which do not support or sent SNI, are directed to the default server.

## OPTIONS
-f, --foreground:

Do not fork server into background.

-d, --debug=num:

Enable verbose network debugging information. num must be between zero and 9999.

-c, --config=FILE:

Specify the configuration file for the server.

-t, --test-config:

Test the provided configuration file and exit. A successful exit error code indicates a valid configuration.

-p, --pid-file=FILE:

Specify a PID file for the server.

-h, --help:

Display usage information and exit.

-v, --version:

Output version of program and exit.

## AUTHENTICATION
Users can be authenticated in multiple ways, which are explained in the following paragraphs. Connected users can be managed using the occtl tool.

### Password authentication
If your system supports Pluggable Authentication Modules (PAM), then ocserv will take advantage of it to password authenticate its users. Otherwise a plain password file similar to the UNIX password file is also supported. In that case the ´ocpasswd´ tool can be used for its management. Note that password authentication can be used in conjunction with certificate authentication.

### GSSAPI authentication
ocserv will take advantage of the MIT Kerberos project GSSAPI libraries, and allow authentication using any method GSSAPI supports. That is, mainly, Kerberos authentication. That is often more useful to be combined with PAM or other password authentication methods so that a fallback mechanism can be used when GSSAPI fails (e.g., when the user doesn´t already have a Kerberos ticket). The GSSAPI authentication is implemented using SPNEGO over HTTP (RFC4559).

### Public key (certificate) authentication
Public key authentication allows the user to be authenticated by the possession of the private key that corresponds to a known to the server public key. That allows the usage of common smart cards for user authentication.

In ocserv, a certificate authority (CA) is used to sign the client certificates. That certificate authority can be local, used only by the server to sign its user´s known public keys which are then given to users in a form of certificates. That authority need also provide a CRL to allow the server to reject the revoked clients (see ca-cert, crl).

In certificate authentication each client presents a certificate and signs data provided by the server, as part of TLS authentication, to prove his possession of the corresponding private key. The certificate need also contain user identifying information, for example, the user ID of the client must be embedded in the certificate´s Distinguished Name (DN), i.e., in the Common Name, or UID fields. For the server to read the name, the cert-user-oid configuration option must be set.

The following examples demonstrate how to use certtool from GnuTLS to generate such CA.

### Generating the CA

```
$ certtool --generate-privkey --outfile ca-key.pem
$ cat << _EOF_ >ca.tmpl
cn = "VPN CA"
organization = "Big Corp"
serial = 1
expiration_days = -1
ca
signing_key
cert_signing_key
crl_signing_key
_EOF_
$ certtool --generate-self-signed --load-privkey ca-key.pem \

           --template ca.tmpl --outfile ca-cert.pem
```

### Generating a local server certificate
The following example generates the server key and certificate pair. The key generated is an RSA one, but different types can be used by specifying the ´ecdsa´ or ´dsa´ options to certtool.

```
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "VPN server"
dns_name = "www.example.com"
dns_name = "vpn1.example.com"
#ip_address = "1.2.3.4"
organization = "MyCompany"
expiration_days = -1
signing_key
encryption_key #only if the generated key is an RSA one
tls_www_server
_EOF_
$ certtool --generate-certificate --load-privkey server-key.pem \

           --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem \

           --template server.tmpl --outfile server-cert.pem
```

From this point the clients need ca-cert.pem to be able to securely connect to the server.

Note that it is a better practice to use two separate RSA keys, one with the signing_key option and another with the encryption_key.

### Generating an external CA-signed server certificate

```
$ certtool --generate-privkey --outfile server-key.pem
$ cat << _EOF_ >server.tmpl
cn = "My server"
dns_name = "www.example.com"
organization = "MyCompany"
expiration_days = -1
signing_key
encryption_key #only if the generated key is an RSA one
tls_www_server
_EOF_
$ certtool --generate-request --load-privkey server-key.pem \

           --template server.tmpl --outfile server-cert.csr
```

At this point you need to provide the server-cert.csr to your CA, and they will send you the server certificate.

### Generating the client certificates
Note that it is recommended to leave detailed personal information out of the certificate as it is sent in clear during TLS authentication. The following process generates a certificate and converts it to PKCS #12 that is protected by a PIN and most clients are able to import (the 3DES cipher is used in the example because it is supported by far more devices than AES).

```
$ certtool --generate-privkey --outfile user-key.pem
$ cat << _EOF_ >user.tmpl
cn = "user"
unit = "admins"
expiration_days = 365
signing_key
tls_www_client
_EOF_
$ certtool --generate-certificate --load-privkey user-key.pem \

           --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem \

           --template user.tmpl --outfile user-cert.pem
$ certtool --to-p12 --load-privkey user-key.pem \

           --pkcs-cipher 3des-pkcs12 \

           --load-certificate user-cert.pem \

           --outfile user.p12 --outder
```

### Revoking a client certificate
To revoke the previous client certificate, i.e., preventing the user from accessing the VPN resources prior to its certificate expiration, use:

```
$ cat << _EOF_ >crl.tmpl
crl_next_update = 365
crl_number = 1
_EOF_
$ cat user-cert.pem >>revoked.pem
$ certtool --generate-crl --load-ca-privkey ca-key.pem \

           --load-ca-certificate ca-cert.pem --load-certificate revoked.pem \

           --template crl.tmpl --outfile crl.pem
```

After that you may want to notify ocserv of the new CRL by using the HUP signal, or wait for it to reload it.

When there are no revoked certificates an empty revocation list should be generated as follows.

```
$ certtool --generate-crl --load-ca-privkey ca-key.pem \

           --load-ca-certificate ca-cert.pem \

           --template crl.tmpl --outfile crl.pem
```

## IMPLEMENTATION NOTES
Note that while this server utilizes privilege separation and all authentication occurs on the security module, this does not apply for TLS client certificate authentication. That is due to TLS protocol limitation.

## NETWORKING CONSIDERATIONS
In certain setups, where a firewall may be blocking ICMP responses, setting the MSS of TCP connections to MTU will eliminate the "black hole" connection issues. See http://lartc.org/howto/lartc.cookbook.mtu-mss.html for instructions to enable it on a Linux system.

## FILES

### ocserv´s configuration file format
By default, if no other file is specified, ocserv looks for its configuration file at /etc/ocserv/ocserv.conf. An example configuration file follows.

```
### The following directives do not change with server reload.
# User authentication method. To require multiple methods to be
# used for the user to login, add multiple auth directives. The values
# in the ´auth´ directive are AND composed (if multiple all must
# succeed).
# Available options: certificate, plain, pam, radius, gssapi.
# Note that authentication methods utilizing passwords cannot be
# combined (e.g., the plain, pam or radius methods).
# certificate:
#  This indicates that all connecting users must present a certificate.
#  The username and user group will be then extracted from it (see
#  cert-user-oid and cert-group-oid). The certificate to be accepted
#  it must be signed by the CA certificate as specified in ´ca-cert´ and
#  it must not be listed in the CRL, as specified by the ´crl´ option.
#
# pam[gid-min=1000]:
#  This enabled PAM authentication of the user. The gid-min option is used
# by auto-select-group option, in order to select the minimum valid group ID.
#
# plain[passwd=/etc/ocserv/ocpasswd,otp=/etc/ocserv/users.otp]
#  The plain option requires specifying a password file which contains
# entries of the following format.
# "username:groupname1,groupname2:encoded-password"
# One entry must be listed per line, and ´ocpasswd´ should be used
# to generate password entries. The ´otp´ suboption allows one to specify
# an oath password file to be used for one time passwords; the format of
# the file is described in https://github.com/archiecobbs/mod-authn-otp/wiki/UsersFile
#
# radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true,nas-identifier=name]:
#  The radius option requires specifying freeradius-client configuration
# file. If the groupconfig option is set, then config-per-user/group will be overridden,
# and all configuration will be read from radius. That also includes the
# Acct-Interim-Interval, and Session-Timeout values.
#
# See doc/README-radius.md for the supported radius configuration attributes.
#
# gssapi[keytab=/etc/key.tab,require-local-user-map=true,tgt-freshness-time=900]
#  The gssapi option allows one to use authentication methods supported by GSSAPI,
# such as Kerberos tickets with ocserv. It should be best used as an alternative
# to PAM (i.e., have pam in auth and gssapi in enable-auth), to allow users with
# tickets and without tickets to login. The default value for require-local-user-map
# is true. The ´tgt-freshness-time´ if set, it would require the TGT tickets presented
# to have been issued within the provided number of seconds. That option is used to
# restrict logins even if the KDC provides long time TGT tickets.
#auth = "pam"
#auth = "pam[gid-min=1000]"
#auth = "plain[passwd=./sample.passwd,otp=./sample.otp]"
auth = "plain[passwd=./sample.passwd]"
#auth = "certificate"
#auth = "radius[config=/etc/radiusclient/radiusclient.conf,groupconfig=true]"
# Specify alternative authentication methods that are sufficient
# for authentication. That is, if set, any of the methods enabled
# will be sufficient to login, irrespective of the main ´auth´ entries.
# When multiple options are present, they are OR composed (any of them
# succeeding allows login).
#enable-auth = "certificate"
#enable-auth = "gssapi"
#enable-auth = "gssapi[keytab=/etc/key.tab,require-local-user-map=true,tgt-freshness-time=900]"
# Accounting methods available:
# radius: can be combined with any authentication method, it provides
#      radius accounting to available users (see also stats-report-time).
#
# pam: can be combined with any authentication method, it provides
#      a validation of the connecting user´s name using PAM. It is
#      superfluous to use this method when authentication is already
#      PAM.
#
# Only one accounting method can be specified.
#acct = "radius[config=/etc/radiusclient/radiusclient.conf]"
# Use listen-host to limit to specific IPs or to the IPs of a provided
# hostname.
#listen-host = [IP|HOSTNAME]
# Use udp-listen-host to limit udp to specific IPs or to the IPs of a provided
# hostname. if not set, listen-host will be used
#udp-listen-host = [IP|HOSTNAME]
# When the server has a dynamic DNS address (that may change),
# should set that to true to ask the client to resolve again on
# reconnects.
#listen-host-is-dyndns = true
# move the listen socket within the specified network namespace
# listen-netns = "foo"
# TCP and UDP port number
tcp-port = 443
udp-port = 443
# The user the worker processes will be run as. This should be a dedicated
# unprivileged user (e.g., ´ocserv´) and no other services should run as this
# user.
run-as-user = nobody
run-as-group = daemon
# socket file used for IPC with occtl. You only need to set that,
# if you use more than a single servers.
#occtl-socket-file = /var/run/occtl.socket
# socket file used for server IPC (worker-main), will be appended with .PID
# It must be accessible within the chroot environment (if any), so it is best
# specified relatively to the chroot directory.
socket-file = /var/run/ocserv-socket
# The default server directory. Does not require any devices present.
#chroot-dir = /var/lib/ocserv
# The key and the certificates of the server
# The key may be a file, or any URL supported by GnuTLS (e.g.,
# tpmkey:uuid=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx;storage=user
# or pkcs11:object=my-vpn-key;object-type=private)
#
# The server-cert file may contain a single certificate, or
# a sorted certificate chain.
# There may be multiple server-cert and server-key directives,
# but each key should correspond to the preceding certificate.
# The certificate files will be reloaded when changed allowing for in-place
# certificate renewal (they are checked and reloaded periodically;
# a SIGHUP signal to main server will force reload).
#server-cert = /etc/ocserv/server-cert.pem
#server-key = /etc/ocserv/server-key.pem
server-cert = ../tests/certs/server-cert.pem
server-key = ../tests/certs/server-key.pem
# Diffie-Hellman parameters. Only needed if for old (pre 3.6.0
# versions of GnuTLS for supporting DHE ciphersuites.
# Can be generated using:
# certtool --generate-dh-params --outfile /etc/ocserv/dh.pem
#dh-params = /etc/ocserv/dh.pem
# In case PKCS #11, TPM or encrypted keys are used the PINs should be available
# in files. The srk-pin-file is applicable to TPM keys only, and is the
# storage root key.
#pin-file = /etc/ocserv/pin.txt
#srk-pin-file = /etc/ocserv/srkpin.txt
# The password or PIN needed to unlock the key in server-key file.
# Only needed if the file is encrypted or a PKCS #11 object. This
# is an alternative method to pin-file.
#key-pin = 1234
# The SRK PIN for TPM.
# This is an alternative method to srk-pin-file.
#srk-pin = 1234
# The Certificate Authority that will be used to verify
# client certificates (public keys) if certificate authentication
# is set.
#ca-cert = /etc/ocserv/ca.pem
ca-cert = ../tests/certs/ca.pem
# The number of sub-processes to use for the security module (authentication)
# processes. Typically this should not be set as the number of processes
# is determined automatically by the initially set maximum number of clients.
#sec-mod-scale = 4
### All configuration options below this line are reloaded on a SIGHUP.
### The options above, will remain unchanged. Note however, that the
### server-cert, server-key, dh-params and ca-cert options will be reloaded
### if the provided file changes, on server reload. That allows certificate
### rotation, but requires the server key to remain the same for seamless
### operation. If the server key changes on reload, there may be connection
### failures during the reloading time.
# Whether to enable seccomp/Linux namespaces worker isolation. That restricts the number of
# system calls allowed to a worker process, in order to reduce damage from a
# bug in the worker process. It is available on Linux systems at a performance cost.
# The performance cost is roughly 2% overhead at transfer time (tested on a Linux 3.17.8).
# Note however, that process isolation is restricted to the specific libc versions
# the isolation was tested at. If you get random failures on worker processes, try
# disabling that option and report the failures you, along with system and debugging
# information at: https://gitlab.com/ocserv/ocserv/issues
isolate-workers = true
# A banner to be displayed on clients after connection
#banner = "Welcome"
# A banner to be displayed on clients before connection
#pre-login-banner = "Welcome"
# Limit the number of clients. Unset or set to zero if unknown. In
# that case the maximum value is ~8k clients.
#max-clients = 1024
max-clients = 16
# Limit the number of identical clients (i.e., users connecting
# multiple times). Unset or set to zero for unlimited.
max-same-clients = 2
# When the server receives connections from a proxy, like haproxy
# which supports the proxy protocol, set this to obtain the correct
# client addresses. The proxy protocol would then be expected in
# the TCP or UNIX socket (not the UDP one). Although both v1
# and v2 versions of proxy protocol are supported, the v2 version
# is recommended as it is more efficient in parsing.
#listen-proxy-proto = true
# Rate limit the number of incoming connections to one every X milliseconds
# (X is the provided value), as the secmod backlog grows. This
# makes the server more resilient (and prevents connection failures) on
# multiple concurrent connections. Set to zero for no limit.
rate-limit-ms = 100
# Stats report time. The number of seconds after which each
# worker process will report its usage statistics (number of
# bytes transferred etc). This is useful when accounting like
# radius is in use.
#stats-report-time = 360
# Stats reset time. The period of time statistics kept by main/sec-mod
# processes will be reset. These are the statistics shown by cmd
# ´occtl show stats´. For daily: 86400, weekly: 604800
# This is unrelated to stats-report-time.
server-stats-reset-time = 604800
# Keepalive in seconds
keepalive = 32400
# Dead peer detection in seconds.
# Note that when the client is behind a NAT this value
# needs to be short enough to prevent the NAT disassociating
# his UDP session from the port number. Otherwise the client
# could have his UDP connection stalled, for several minutes.
dpd = 90
# Dead peer detection for mobile clients. That needs to
# be higher to prevent such clients being awaken too
# often by the DPD messages, and save battery.
# The mobile clients are distinguished from the header
# ´X-AnyConnect-Identifier-Platform´.
mobile-dpd = 1800
# If using DTLS, and no UDP traffic is received for this
# many seconds, attempt to send future traffic over the TCP
# connection instead, in an attempt to wake up the client
# in the case that there is a NAT and the UDP translation
# was deleted. If this is unset, do not attempt to use this
# recovery mechanism.
switch-to-tcp-timeout = 25
# MTU discovery (DPD must be enabled)
try-mtu-discovery = false
# To enable load-balancer connection draining, set server-drain-ms to a value
# higher than your load-balancer health probe interval.
#server-drain-ms = 15000
# If you have a certificate from a CA that provides an OCSP
# service you may provide a fresh OCSP status response within
# the TLS handshake. That will prevent the client from connecting
# independently on the OCSP server.
# You can update this response periodically using:
# ocsptool --ask --load-cert=your_cert --load-issuer=your_ca --outfile response
# Make sure that you replace the following file in an atomic way.
#ocsp-response = /etc/ocserv/ocsp.der
# The object identifier that will be used to read the user ID in the client
# certificate. The object identifier should be part of the certificate´s DN
# Useful OIDs are:
#  CN = 2.5.4.3, UID = 0.9.2342.19200300.100.1.1, SAN(rfc822name)
cert-user-oid = 0.9.2342.19200300.100.1.1
# The object identifier that will be used to read the user group in the
# client certificate. The object identifier should be part of the certificate´s
# DN. If the user may belong to multiple groups, then use multiple such fields
# in the certificate´s DN. Useful OIDs are:
#  OU (organizational unit) = 2.5.4.11
#cert-group-oid = 2.5.4.11
# The revocation list of the certificates issued by the ´ca-cert´ above.
# See the manual to generate an empty CRL initially. The CRL will be reloaded
# periodically when ocserv detects a change in the file. To force a reload use
# SIGHUP.
#crl = /etc/ocserv/crl.pem
# Uncomment this to enable compression negotiation (LZS, LZ4).
#compression = true
# Set the minimum size under which a packet will not be compressed.
# That is to allow low-latency for VoIP packets. The default size
# is 256 bytes. Modify it if the clients typically use compression
# as well of VoIP with codecs that exceed the default value.
#no-compress-limit = 256
# GnuTLS priority string; note that SSL 3.0 is disabled by default
# as there are no openconnect (and possibly anyconnect clients) using
# that protocol. The string below does not enforce perfect forward
# secrecy, in order to be compatible with legacy clients.
#
# Note that the most performant ciphersuites are the moment are the ones
# involving AES-GCM. These are very fast in x86 and x86-64 hardware, and
# in addition require no padding, thus taking full advantage of the MTU.
# For that to be taken advantage of, the openconnect client must be
# used, and the server must be compiled against GnuTLS 3.2.7 or later.
# Use "gnutls-cli --benchmark-tls-ciphers", to see the performance
# difference with AES_128_CBC_SHA1 (the default for anyconnect clients)
# in your system.
tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-VERS-SSL3.0:-VERS-TLS1.0:-VERS-TLS1.1"
# More combinations in priority strings are available, check
# http://gnutls.org/manual/html_node/Priority-Strings.html
# E.g., the string below enforces perfect forward secrecy (PFS)
# on the main channel.
#tls-priorities = "NORMAL:%SERVER_PRECEDENCE:%COMPAT:-RSA:-VERS-SSL3.0:-ARCFOUR-128"
# That option requires the established DTLS channel to use the same
# cipher as the primary TLS channel.Note also, that this option implies
# that the dtls-legacy option is false; this option cannot be enforced
# in the legacy/compat protocol.
#match-tls-dtls-ciphers = true
# The time (in seconds) that a client is allowed to stay connected prior
# to authentication
auth-timeout = 240
# The time (in seconds) that a client is allowed to stay idle (no traffic)
# before being disconnected. Unset to disable.
#idle-timeout = 1200
# The time (in seconds) that a client is allowed to stay connected
# Unset to disable. When set a client will be disconnected after being
# continuously connected for this amount of time, and its cookies will
# be invalidated (i.e., re-authentication will be required).
#session-timeout = 86400
# The time (in seconds) that a mobile client is allowed to stay idle (no
# traffic) before being disconnected. Unset to disable.
#mobile-idle-timeout = 2400
# The time (in seconds) that a client is not allowed to reconnect after
# a failed authentication attempt.
min-reauth-time = 300
# Banning clients in ocserv works with a point system. IP addresses
# that get a score over that configured number are banned for
# min-reauth-time seconds. By default a wrong password attempt is 10 points,
# a KKDCP POST is 1 point, and a connection is 1 point. Note that
# due to different processes being involved the count of points
# will not be real-time precise. Local subnet IPs are exempt to allow
# services that check for process health.
#
# Set to zero to disable.
max-ban-score = 80
# The time (in seconds) that all score kept for a client is reset.
ban-reset-time = 1200
# In case you´d like to change the default points.
#ban-points-wrong-password = 10
#ban-points-connection = 1
#ban-points-kkdcp = 1
# Cookie timeout (in seconds)
# Once a client is authenticated he´s provided a cookie with
# which he can reconnect. That cookie will be invalidated if not
# used within this timeout value. This cookie remains valid, during
# the user´s connected time, and after user disconnection it
# remains active for this amount of time. That setting should allow a
# reasonable amount of time for roaming between different networks.
cookie-timeout = 300
# If this is enabled (not recommended) the cookies will stay
# valid even after a user manually disconnects, and until they
# expire. This may improve roaming with some broken clients.
#persistent-cookies = true
# Whether roaming is allowed, i.e., if true a cookie is
# restricted to a single IP address and cannot be re-used
# from a different IP.
deny-roaming = false
# ReKey time (in seconds)
# ocserv will ask the client to refresh keys periodically once
# this amount of seconds is elapsed. Set to zero to disable (note
# that, some clients fail if rekey is disabled).
rekey-time = 172800
# ReKey method
# Valid options: ssl, new-tunnel
#  ssl: Will perform an efficient rehandshake on the channel allowing
#       a seamless connection during rekey.
#  new-tunnel: Will instruct the client to discard and re-establish the channel.
#       Use this option only if the connecting clients have issues with the ssl
#       option.
rekey-method = ssl
# Script to call when a client connects and obtains an IP.
# The following parameters are passed on the environment.
# REASON, VHOST, USERNAME, GROUPNAME, DEVICE, IP_REAL (the real IP of the client),
# REMOTE_HOSTNAME (the remotely advertised hostname), IP_REAL_LOCAL
# (the local interface IP the client connected), IP_LOCAL
# (the local IP in the P-t-P connection), IP_REMOTE (the VPN IP of the client),
# IPV6_LOCAL (the IPv6 local address if there are both IPv4 and IPv6
# assigned), IPV6_REMOTE (the IPv6 remote address), IPV6_PREFIX, and
# ID (a unique numeric ID); REASON may be "connect" or "disconnect".
# In addition the following variables OCSERV_ROUTES (the applied routes for this
# client), OCSERV_NO_ROUTES, OCSERV_DNS (the DNS servers for this client),
# will contain a space separated list of routes or DNS servers. A version
# of these variables with the 4 or 6 suffix will contain only the IPv4 or
# IPv6 values. The connect script must return zero as exit code, or the
# client connection will be refused.
# The disconnect script will receive the additional values: STATS_BYTES_IN,
# STATS_BYTES_OUT, STATS_DURATION that contain a 64-bit counter of the bytes
# output from the tun device, and the duration of the session in seconds.
#connect-script = /usr/bin/myscript
#disconnect-script = /usr/bin/myscript
# This script is to be called when the client´s advertised hostname becomes
# available. It will contain REASON with "host-update" value and the
# variable REMOTE_HOSTNAME in addition to the connect variables.
#host-update-script = /usr/bin/myhostnamescript
# UTMP
# Register the connected clients to utmp. This will allow viewing
# the connected clients using the command ´who´.
#use-utmp = true
# Whether to enable support for the occtl tool (i.e., either through D-BUS,
# or via a unix socket).
use-occtl = true
# PID file. It can be overridden in the command line.
pid-file = /var/run/ocserv.pid
# Log Level. It can be overridden in the command line with the -d option.
# All messages at the configure level and lower will be displayed.
# Supported levels (default 0)
#   0 default (Same as basic)
#   1 basic
#   2 info
#   3 debug
#   4 http
#   8 sensitive
#   9 TLS
log-level = 1
# Set the protocol-defined priority (SO_PRIORITY) for packets to
# be sent. That is a number from 0 to 6 with 0 being the lowest
# priority. Alternatively this can be used to set the IP Type-
# Of-Service, by setting it to a hexadecimal number (e.g., 0x20).
# This can be set per user/group or globally.
#net-priority = 3
# Set the VPN worker process into a specific cgroup. This is Linux
# specific and can be set per user/group or globally.
#cgroup = "cpuset,cpu:test"
#
# Network settings
#
# The name to use for the tun device
device = vpns
# Whether the generated IPs will be predictable, i.e., IP stays the
# same for the same user when possible.
predictable-ips = true
# The default domain to be advertised. Multiple domains (functional on
# openconnect clients) can be provided in a space separated list.
default-domain = example.com
#default-domain = "example.com one.example.com"
# The pool of addresses that leases will be given from. If the leases
# are given via Radius, or via the explicit-ip? per-user config option then
# these network values should contain a network with at least a single
# address that will remain under the full control of ocserv (that is
# to be able to assign the local part of the tun device address).
# Note that, you could use addresses from a subnet of your LAN network if you
# enable [proxy arp in the LAN interface](http://ocserv.gitlab.io/www/recipes-ocserv-pseudo-bridge.html);
# in that case it is recommended to set ping-leases to true.
ipv4-network = 192.168.1.0
ipv4-netmask = 255.255.255.0
# An alternative way of specifying the network:
#ipv4-network = 192.168.1.0/24
# The IPv6 subnet that leases will be given from.
#ipv6-network = fda9:4efe:7e3b:03ea::/48
# Specify the size of the network to provide to clients. It is
# generally recommended to provide clients with a /64 network in
# IPv6, but any subnet may be specified. To provide clients only
# with a single IP use the prefix 128.
#ipv6-subnet-prefix = 128
#ipv6-subnet-prefix = 64
# Whether to tunnel all DNS queries via the VPN. This is the default
# when a default route is set.
#tunnel-all-dns = true
# The advertised DNS server. Use multiple lines for
# multiple servers.
# dns = fc00::4be0
dns = 192.168.1.2
# The NBNS server (if any)
#nbns = 192.168.1.3
# The domains over which the provided DNS should be used. Use
# multiple lines for multiple domains.
#split-dns = example.com
# Prior to leasing any IP from the pool ping it to verify that
# it is not in use by another (unrelated to this server) host.
# Only set to true, if there can be occupied addresses in the
# IP range for leases.
ping-leases = false
# Use this option to set a link MTU value to the incoming
# connections. Unset to use the default MTU of the TUN device.
# Note that the MTU is negotiated using the value set and the
# value sent by the peer.
#mtu = 1420
# Unset to enable bandwidth restrictions (in bytes/sec). The
# setting here is global, but can also be set per user or per group.
#rx-data-per-sec = 40000
#tx-data-per-sec = 40000
# The number of packets (of MTU size) that are available in
# the output buffer. The default is low to improve latency.
# Setting it higher will improve throughput.
#output-buffer = 10
# Routes to be forwarded to the client. If you need the
# client to forward routes to the server, you may use the
# config-per-user/group or even connect and disconnect scripts.
#
# To set the server as the default gateway for the client just
# comment out all routes from the server, or use the special keyword
# ´default´.
route = 10.10.10.0/255.255.255.0
route = 192.168.0.0/255.255.0.0
#route = fef4:db8:1000:1001::/64
#route = default
# Subsets of the routes above that will not be routed by
# the server.
no-route = 192.168.5.0/255.255.255.0
# Note the that following two firewalling options currently are available
# in Linux systems with iptables software.
# If set, the script /usr/bin/ocserv-fw will be called to restrict
# the user to its allowed routes and prevent him from accessing
# any other routes. In case of defaultroute, the no-routes are restricted.
# All the routes applied by ocserv can be reverted using /usr/bin/ocserv-fw
# --removeall. This option can be set globally or in the per-user configuration.
#restrict-user-to-routes = true
# This option implies restrict-user-to-routes set to true. If set, the
# script /usr/bin/ocserv-fw will be called to restrict the user to
# access specific ports in the network. This option can be set globally
# or in the per-user configuration.
#restrict-user-to-ports = "tcp(443), tcp(80), udp(443), sctp(99), tcp(583), icmp(), icmpv6()"
# You could also use negation, i.e., block the user from accessing these ports only.
#restrict-user-to-ports = "!(tcp(443), tcp(80))"
# When set to true, all client´s iroutes are made visible to all
# connecting clients except for the ones offering them. This option
# only makes sense if config-per-user is set.
#expose-iroutes = true
# Groups that a client is allowed to select from.
# A client may belong in multiple groups, and in certain use-cases
# it is needed to switch between them. For these cases the client can
# select prior to authentication. Add multiple entries for multiple groups.
# The group may be followed by a user-friendly name in brackets.
#select-group = group1
#select-group = group2[My special group]
# The name of the (virtual) group that if selected it would assign the user
# to its default group.
#default-select-group = DEFAULT
# Instead of specifying manually all the allowed groups, you may instruct
# ocserv to scan all available groups and include the full list.
#auto-select-group = true
# Configuration files that will be applied per user connection or
# per group. Each file name on these directories must match the username
# or the groupname.
# The options allowed in the configuration files are dns, nbns,
#  ipv?-network, ipv4-netmask, rx/tx-data-per-sec, iroute, route, no-route,
#  explicit-ipv4, explicit-ipv6, net-priority, deny-roaming, no-udp,
#  keepalive, dpd, mobile-dpd, max-same-clients, tunnel-all-dns,
#  restrict-user-to-routes, cgroup, stats-report-time,
#  mtu, idle-timeout, mobile-idle-timeout, restrict-user-to-ports,
#  split-dns and session-timeout.
#
# Note that the ´iroute´ option allows one to add routes on the server
# based on a user or group. The syntax depends on the input accepted
# by the commands route-add-cmd and route-del-cmd (see below). The no-udp
# is a boolean option (e.g., no-udp = true), and will prevent a UDP session
# for that specific user or group. The hostname option will set a
# hostname to override any proposed by the user. Note also, that, any
# routes, no-routes, DNS or NBNS servers present will overwrite the global ones.
#config-per-user = /etc/ocserv/config-per-user/
#config-per-group = /etc/ocserv/config-per-group/
# When config-per-xxx is specified and there is no group or user that
# matches, then utilize the following configuration.
#default-user-config = /etc/ocserv/defaults/user.conf
#default-group-config = /etc/ocserv/defaults/group.conf
# The system command to use to setup a route. %{R} will be replaced with the
# route/mask, %{RI} with the route in CIDR format, and %{D} with the (tun) device.
#
# The following example is from linux systems. %{R} should be something
# like 192.168.2.0/255.255.255.0 and %{RI} 192.168.2.0/24 (the argument of iroute).
#route-add-cmd = "ip route add %{R} dev %{D}"
#route-del-cmd = "ip route delete %{R} dev %{D}"
# This option allows one to forward a proxy. The special keywords ´%{U}´
# and ´%{G}´, if present will be replaced by the username and group name.
#proxy-url = http://example.com/
#proxy-url = http://example.com/%{U}/
# This option allows you to specify a URL location where a client can
# post using MS-KKDCP, and the message will be forwarded to the provided
# KDC server. That is a translation URL between HTTP and Kerberos.
# In MIT kerberos you´ll need to add in realms:
#   EXAMPLE.COM = {
#     kdc = https://ocserv.example.com/KdcProxy
#     http_anchors = FILE:/etc/ocserv-ca.pem
#   }
# In some distributions the krb5-k5tls plugin of kinit is required.
#
# The following option is available in ocserv, when compiled with GSSAPI support.
#kkdcp = "SERVER-PATH KERBEROS-REALM PROTOCOL@SERVER:PORT"
#kkdcp = "/KdcProxy KERBEROS.REALM udp@127.0.0.1:88"
#kkdcp = "/KdcProxy KERBEROS.REALM tcp@127.0.0.1:88"
#kkdcp = "/KdcProxy KERBEROS.REALM tcp@[::1]:88"
# Client profile xml. This can be used to advertise alternative servers
# to the client. A minimal file can be:
# <?xml version="1.0" encoding="UTF-8"?>
# <AnyConnectProfile xmlns="http://schemas.xmlsoap.org/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.xmlsoap.org/encoding/ AnyConnectProfile.xsd">
#   <ServerList>
#       <HostEntry>
#               <HostName>VPN Server name</HostName>
#               <HostAddress>localhost</HostAddress>
#       </HostEntry>
#   </ServerList>
# </AnyConnectProfile>
#
# Other fields may be used by some of the CISCO clients.
# This file must be accessible from inside the worker´s chroot.
# Note that:
#  (1) enabling this option is not recommended as it will allow the
#      worker processes to open arbitrary files (when isolate-workers is
#      set to true).
#  (2) This option cannot be set per-user or per-group; only the global
#      version is being sent to client.
#user-profile = profile.xml
#
# The following options are for (experimental) AnyConnect client
# compatibility.
# This option will enable the pre-draft-DTLS version of DTLS, and
# will not require clients to present their certificate on every TLS
# connection. It must be set to true to support legacy CISCO clients
# and openconnect clients < 7.08. When set to true, it implies dtls-legacy = true.
cisco-client-compat = true
# This option allows one to disable the DTLS-PSK negotiation (enabled by default).
# The DTLS-PSK negotiation was introduced in ocserv 0.11.5 to deprecate
# the pre-draft-DTLS negotiation inherited from AnyConnect. It allows the
# DTLS channel to negotiate its ciphers and the DTLS protocol version.
#dtls-psk = false
# This option allows one to disable the legacy DTLS negotiation (enabled by default,
# but that may change in the future).
# The legacy DTLS uses a pre-draft version of the DTLS protocol and was
# from AnyConnect protocol. It has several limitations, that are addressed
# by the dtls-psk protocol supported by openconnect 7.08+.
dtls-legacy = true
# This option will enable the X-CSTP-Client-Bypass-Protocol (disabled by default).
# If the server has not configured an IPv6 or IPv4 address pool, enabling this option
# will instruct the client to bypass the server for that IP protocol. The option is
# currently only understood by Anyconnect clients.
client-bypass-protocol = false
#Advanced options
# Option to allow sending arbitrary custom headers to the client after
# authentication and prior to VPN tunnel establishment. You shouldn´t
# need to use this option normally; if you do and you think that
# this may help others, please send your settings and reason to
# the openconnect mailing list. The special keywords ´%{U}´
# and ´%{G}´, if present will be replaced by the username and group name.
#custom-header = "X-My-Header: hi there"
# An example virtual host with different authentication methods serviced
# by this server.
[vhost:www.example.com]
auth = "certificate"
ca-cert = ../tests/certs/ca.pem
# The certificate set here must include a ´dns_name´ corresponding to
# the virtual host name.
server-cert = ../tests/certs/server-cert-secp521r1.pem
server-key = ../tests/certs/server-key-secp521r1.pem
ipv4-network = 192.168.2.0
ipv4-netmask = 255.255.255.0
cert-user-oid = 0.9.2342.19200300.100.1.1
```

## SEE ALSO
occtl(8), ocpasswd(8), openconnect(8)

## COPYRIGHT
Copyright (C) 2013-2018 Nikos Mavrogiannopoulos and others, all rights reserved. This program is released under the terms of the GNU General Public License, version 2.

## AUTHORS
Written by Nikos Mavrogiannopoulos. Many people have contributed to it.


ocspcheck

package: ocspcheck

title: ocspcheck(8)

text:
# ocspcheck(8)

## NAME
ocspcheck — check a certificate for validity against its OCSP responder

## SYNOPSIS
ocspcheck

[-Nv] [-C CAfile] [-i staplefile] [-o staplefile] file

## DESCRIPTION
The ocspcheck utility validates a PEM format certificate against the OCSP responder encoded in the certificate specified by the file argument. Normally it should be used for checking server certificates and maintaining saved OCSP responses to be used for OCSP stapling.

The options are as follows:

-C CAfile

Specify a PEM format root certificate bundle to use for the validation of requests. By default no certificates are used beyond those in the certificate chain provided by the file argument.

-i staplefile

Specify an input filename from which a DER-encoded OCSP response will be read instead of fetching it from the OCSP server. A filename of ‘-’ will read the response from standard input.

-N

Do not use a nonce value in the OCSP request, or validate that the nonce was returned in the OCSP response. By default a nonce is always used and validated when retrieving a response from an OCSP server. The use of this flag is a security risk as it will allow OCSP responses to be replayed. It should not be used unless the OCSP server does not support the use of OCSP nonces.

-o staplefile

Specify an output filename where the DER encoded response from the OCSP server will be written, if the OCSP response validates. A filename of ‘-’ will write the response to standard output. By default the response is not saved.

-v

Increase verbosity. This flag may be specified multiple times to get more verbose output. The default behaviour is to be silent unless something goes wrong.

## EXIT STATUS
The ocspcheck utility exits 0 if the OCSP response validates for the certificate in file and all output is successfully written out. ocspcheck exits >0 if an error occurs or the OCSP response fails to validate.

## SEE ALSO
nc(1), tls_config_set_ocsp_staple_file(3), tls_config_set_ocsp_staple_mem(3), httpd(8)

## HISTORY
The ocspcheck utility first appeared in OpenBSD 6.1.

## AUTHORS
ocspcheck was written by Bob Beck.

## CAVEATS
While ocspcheck could possibly be used in scripts to query responders for server certificates seen on client connections, this is almost always a bad idea. God kills a kitten every time you make an OCSP query from the client side of a TLS connection.

## BUGS
ocspcheck will create the output file if it does not exist. On failure a newly created output file will not be removed.


oddjobd

package: oddjob

title: oddjobd(8)

text:
# oddjobd(8)

## NAME
oddjobd - privileged operations for unprivileged processes

## SYNOPSIS
oddjobd [-n] [-d] [-p pidfile] [-c configfile] [-S] [-t timeout]

## DESCRIPTION
The oddjobd daemon provides the com.redhat.oddjob service on the system-wide message bus. Each facility which oddjobd provides is provided as a separate D-Bus method.

Any method can be invoked by name by any user, subject to access controls enforced by both D-Bus and oddjobd.

Most methods are implemented as helper programs.

## OPTIONS
-n

Do not fork and become a daemon process.

-d

Print debugging messages to stderr. Implies -n.

-p pidfile

Store the daemon's process ID in the named file.

-c /etc/oddjobd.conf

Read the daemon's configuration from the named file.

-S

Connect to the session bus instead of the system bus. Used for testing only.

-t timeout

Specifies the amount of time which will pass between attempts to reconnect to the bus if oddjobd is disconnected for any reason. If the specified timeout is above 5, then oddjobd will first attempt to connect up to 10 times at intervals of 5 seconds. The default reconnect timeout is 30 seconds.

## SIGNALS
SIGHUP

Reload the configuration. Client requests which are in the process of being served will run to completion even if the newly-loaded configuration does not include the service, object, interface, or method.

## SEE ALSO
oddjob_request(1) oddjob.conf(5) oddjobd.conf(5)


package: oddjob-gpupdate

title: pam_oddjob_gpupdate(8)

text:
# pam_oddjob_gpupdate(8)

## NAME
pam_oddjob_gpupdate.so - PAM module to update group policy via oddjob

## SYNOPSIS
session optional /lib/security/pam_oddjob_gpupdate.so

## DESCRIPTION
The pam_oddjob_gpupdate.so module checks if the user exists it invokes the gpupdatefor method of the ru.basealt.oddjob_gpupdate service for the PAM_USER if the module is running with superuser privileges. Otherwise, it ignores.

If D-Bus has not been configured to allow the calling application to invoke these methods provided as part of the ru.basealt.oddjob_gpupdate interface of the / object provided by the ru.basealt.oddjob_gpupdate service, then oddjobd will not receive the request and an error will be returned by D-Bus.

If oddjobd has not been configured to provide these methods, or the user is not authorized to use them, then oddjobd will ignore the module's requests.

## OPTIONS
dbus_timeout

D-Bus oddjob request timeout in seconds

What oddjobd does in response to the module's request is controlled by the daemon's configuration file, typically /etc/oddjobd.conf.d/oddjobd-gpupdate.conf.

## SEE ALSO
oddjob_request(1) oddjob.conf(5) oddjobd.conf(5) oddjobd(8)


package: oddjob-mkhomedir

title: pam_oddjob_mkhomedir(8)

text:
# pam_oddjob_mkhomedir(8)

## NAME
pam_oddjob_mkhomedir.so - PAM module to create users home directory via oddjob

## SYNOPSIS
session optional /lib/security/pam_oddjob_mkhomedir.so

## DESCRIPTION
The pam_oddjob_mkhomedir.so module checks if the user's home directory exists, and if it does not, it invokes the mkhomedirfor method of the com.redhat.oddjob_mkhomedir service for the PAM_USER if the module is running with superuser privileges. Otherwise, it invokes the mkmyhomedir method.

The location of the skeleton directory and the default umask are determined by the values of HOME_MODE or UMASK (as a fallback) variables in /etc/login.defs, so they can not be specified as arguments to this module.

If D-Bus has not been configured to allow the calling application to invoke these methods provided as part of the com.redhat.oddjob_mkhomedir interface of the / object provided by the com.redhat.oddjob_mkhomedir service, then oddjobd will not receive the request and an error will be returned by D-Bus.

If oddjobd has not been configured to provide these methods, or the user is not authorized to use them, then oddjobd will ignore the module's requests.

## OPTIONS
The module takes no options. What oddjobd does in response to the module's request is controlled by the daemon's configuration file, typically /etc/oddjobd.conf.d/oddjobd-mkhomedir.conf.

## SEE ALSO
oddjob_request(1) oddjob.conf(5) oddjobd.conf(5) oddjobd(8)


iscsi-gen-initiatorname

package: open-iscsi

title: iscsi-gen-initiatorname(8)

text:
# iscsi-gen-initiatorname(8)

## NAME
iscsi-gen-initiatorname - smart iSCSI initiator name generation tool

## SYNOPSIS
iscsi-gen-initiatorname [OPTIONS]

## DESCRIPTION
iscsi-gen-initiatorname generates an iSCSI Initiator Name in the initiatorname.iscsi file. It is an error to try to overwrite an existing Initiator Name, unless the -f (force) option is supplied.

The Initiator Name will be taken from the kernel command line, if present (from the rd.initiatorname parameter), else from the iBFT subsystem (if present in sysfs), else it will be generated using the iscsi-iname command.

It is an error if both the kernel command-line Initiator Name and the iBFT Initiator Name are both set, and they are different. it is also an error to try to write over an Initiator Name file if it read-only, or to create one if its directory is not writable.

You must be root to run this command.

## OPTIONS
[-h]

Display a help message and exit.

[-f]

Force overwrite of existing initiator name, if present.

[-p]IQN-PREFIX

Use IQN-PREFIX as the prefix to the IQN generated, instead of the default of iqn.1996-04.de.suse:01.

## FILES
/etc/iscsi/initiatorname.iscsi

The file containing the initiator name. Do not edit manually.

## SEE ALSO
iscsi-iname(8)

## AUTHORS
Open-iSCSI project <http://www.open-iscsi.com/>

Hannes Reinecke <hare@suse.de>

Lee Duncan <lduncan@suse.com>


iscsi-iname

title: iscsi-iname(8)

summary: iSCSI initiator name generation tool

text:
# iscsi-iname(8)

## NAME
iscsi-iname - iSCSI initiator name generation tool

## SYNOPSIS
iscsi-iname [OPTION]

## DESCRIPTION
iscsi-iname generates a unique iSCSI node name on every invocation.

## OPTIONS
[-h|--help]

Display help

[-p=]prefix

Use the prefix passed in instead of the default "iqn.2016-04.com.open-iscsi"

## AUTHORS
Open-iSCSI project <http://www.open-iscsi.com/>

Mike Christie <mchristi@redhat.com>


title: iscsi_discovery(8)

summary: discover iSCSI targets

text:
# iscsi_discovery(8)

## NAME
iscsi_discovery - discover iSCSI targets

## SYNOPSIS
iscsi_discovery <IP> [-p <port>] [-d] [ -t <tcp|iser> [-f] ] [-m] [-l]

## DESCRIPTION
Perform send-targets discovery to the specified IP. If a discovery record is generated, try to login to the portal using the preferred transport (-t flag specifies the requested transport type, TCP is the default). If login using a certain transport succeeds, mark the portal for automatic login (unless -m flag is used), and disconnect (unless -l flag is used).

For iSCSI discovery to work, open-iscsi services must be running. i.e. iscsid should be up, and the iSCSI modules loaded. This is best accomplished by the init.d startup script.

[-p=]port-number

set the port number (default is 3260).

[-d]

print debugging information.

[-t=]transport-type

set transport (default is tcp).

[-f]

force specific transport - disable the fallback to tcp (default is fallback enabled). force the transport specified by the argument of the -t flag.

[-m]

manual startup - will set manual startup (default is automatic startup).

[-l]

login - login to the new discovered nodes (default is false).

## AUTHOR
Written by Dan Bar Dov

## REPORTING BUGS
Report bugs to <erezzi.list@gmail.com>.

## COPYRIGHT
Copyright © Voltaire Ltd. 2006.


title: iscsi_fw_login(8)

summary: Login to all iSCSI Firmware targets

text:
# iscsi_fw_login(8)

## NAME
iscsi_fw_login - Login to all iSCSI Firmware targets

## SYNOPSIS
iscsi_fw_login

## DESCRIPTION
This helper function logs into all known iSCSI firmware targets.

It is meant as a helper function to be called by udev when new firmware targets are detected asynchronously.

## AUTHOR
Written by Lee Duncan

## REPORTING BUGS
Report bugs to <lduncan@suse.com>.

## COPYRIGHT
Copyright © 2015 Lee Duncan <lduncan@suse.com>


iscsiadm

title: iscsiadm(8)

summary: open-iscsi administration utility

text:
# iscsiadm(8)

## NAME
iscsiadm - open-iscsi administration utility

## SYNOPSIS
iscsiadm -m discoverydb [-hV] [-d debug_level] [-P printlevel] [-I iface -t type -p ip:port [-lD] ] | [ [-p ip:port -t type] [-o operation] [-n name] [-v value] [-lD] ]

iscsiadm -m discovery [-hV] [-d debug_level] [-P printlevel] [-I iface] [-t type] [-p ip:port] [-l]

iscsiadm -m node [-hV] [-d debug_level] [-P printlevel] [-L all,manual,automatic,onboot] [-W] [-U all,manual,automatic,onboot] [-S] [ [-T targetname -p ip:port -I iface] [-l|-u|-R|-s] ] [ [-o operation] [-n name] [-v value] [-p ip:port] ]

iscsiadm -m session [-hV] [-d debug_level] [-P printlevel] [-r sessionid|sysfsdir [-R] [-u|-s|-o new] ]

iscsiadm -m iface [-hV] [-d debug_level] [-P printlevel] [-I ifacename | -H hostno|MAC] [ [-o operation] [-n name] [-v value] ] [ -C ping [-a ip] [-b packetsize] [-c count] [-i interval] ]

iscsiadm -m fw [-d debug_level] [-l] [-W] [-n name] [-v value]

iscsiadm -m host [-P printlevel] [-H hostno|MAC] [ [-C chap [-x chap_tbl_idx] ] | [-C flashnode [-A portal_type] [-x flashnode_idx] ] | [-C stats] ] [ [-o operation] [-n name] [-v value] ]

iscsiadm -k priority

## DESCRIPTION
The iscsiadm utility is a command-line tool allowing discovery and login to iSCSI targets, as well as access and management of the open-iscsi database.

Open-iscsi does not use the term node as defined by the iSCSI RFC, where a node is a single iSCSI initiator or target. Open-iscsi uses the term node to refer to a portal on a target.

For session mode, a session id (sid) is used. The sid of a session can be found by running iscsiadm -m session -P 1. The session id and sysfs path are not currently persistent and is partially determined by when the session is setup.

## NOTES
Many of the node and discovery operations require that the iSCSI daemon (iscsid) be running. If running on a system that uses systemd, the daemon may start up automatically, if enabled, when needed.

Open-iscsi has two groups of files it needs to store or get access to, while running: the HOMEDIR and the DBROOT. The following describes them:

Home Directory

The home directory for open-iscsi is /etc/iscsi. This is where it keeps it's configuration file (iscsid.conf) and it's initiator name file (initiatorname.iscsi).

Database Root Directory

The database root directory for open-iscsi is /var/lib/iscsi. This is where it keeps its flat database files, such as it's list of nodes (see below).

## OPTIONS
-a, --ip=ipaddr

ipaddr can be IPv4 or IPv6.

This option is only valid for ping submode.

-A, --portal_type=[ipv4|ipv6]

Specify the portal type for the new flash node entry to be created.

This option is only valid for flashnode submode of host mode and only with new operation.

-b, --packetsize=packetsize

Specify the ping packetsize.

This option is only valid for ping submode.

-c, --count=count

count specifies the number of ping iterations.

This option is only valid for ping submode.

-C, --submode=op

Specify the submode for mode. op must be name of submode.

Currently iscsiadm supports ping as a submode for iface. For example:

iscsiadm -m iface -I ifacename -C ping -a ipaddr -b packetsize -c count -i interval

For host, it supports chap, flashnode and stats as submodes. For example:

iscsiadm -m host -H hostno -C chap -x chap_tbl_idx -o operation

iscsiadm -m host -H hostno -C flashnode -x flashnode_idx -o operation

iscsiadm -m host -H hostno -C stats

-d, --debug=debug_level

print debugging information. Valid values for debug_level are 0 to 8.

-h, --help

display help text and exit

-H, --host=[hostno|MAC]

The host argument specifies the SCSI host to use for the operation. It can be the scsi host number assigned to the host by the kernel's scsi layer, or the MAC address of a scsi host.

-i, --interval=interval

interval specifies the delay between two ping iterations.

This option is only valid for ping submode.

-I, --interface=[iface]

The interface argument specifies the iSCSI interface to use for the operation. iSCSI interfaces (iface) are defined in /var/lib/iscsi/ifaces. For hardware iSCSI (e.g. qla4xxx) the iface configuration must have the hardware address (iface.hwaddress = port's MAC address) and the driver/transport_name (iface.transport_name). The iface's name is then the filename of the iface configuration. For software iSCSI, the iface configuration must have either the hardware address (iface.hwaddress), or the network layer's interface name (iface.net_ifacename), and it must have the driver/transport_name.

The available drivers/iscsi_transports are tcp (software iSCSI over TCP/IP), iser (software iSCSI over InfiniBand), qla4xxx (Qlogic 4XXXX and 82XXX HBAs), cxgb3i and cxgb4i (Chelsio T3 and T4 adapters), bnx2i (QLogic Netextreme II adapters), be2iscsi (Emulex 10G adapter), qedi (QLogic QEDI 25/40/100Gb adapter), and ocs (Emulex One Connect storage). Some of these are considered experimental, as they are not fully tested.

The hwaddress is the MAC address or for software iSCSI it may be the special value default which directs the initiator to not bind the session to a specific hardware resource and instead allow the network or InfiniBand layer to decide what to do. There is no need to create an iface configuration with the default behavior. If you do not specify an iface, then the default behavior is used.

As mentioned above there is a special iface name default. There are others which do not bind the session to a specific card, but instead bind the session to the transport: iser, cxgb3i, cxgb4i, and bnx2i.

In discovery mode multiple interfaces can be specified by passing in multiple -I/--interface instances. For example:

sh# iscsiadm -m discoverydb -t st -p ip:port -I iface0 -I iface2 --discover

Will direct iscsiadm to setup the node db to create records which will create sessions through the two interfaces passed in.

In node mode, only a single interface is supported in each call to iscsiadm.

This option is valid for discovery, node and iface modes.

-k, --killiscsid=[priority]

Currently priority must be zero. This will immediately stop all iscsid operations and shutdown iscsid. It does not logout any sessions. Running this command is the same as doing killall iscsid. Neither should normally be used, because if iscsid is doing error recovery or if there is an error while iscsid is not running, the system may not be able to recover. This command and iscsid's SIGTERM handling are experimental.

-D, --discover

Discover targets using the discovery record with the recid matching the the discovery type and portal passed in. If there is no matching record, it will be created using the iscsid.conf discovery settings. This must be passed in to discoverydb mode to instruct iscsiadm to perform discovery.

This option is only valid for SendTargets discovery mode.

-l, --login

For node and fw modes, login to a specified record. For discovery mode, login to all discovered targets.

This option is only valid for discovery, node, and fw modes. For fw mode only, name and value pairs can optionally be passed in, so that those values get used for the sessions created. In this case, no op is needed, since update is assumed.

-L, --loginall=[all|manual|automatic|onboot]

For node mode, login to all sessions with the node or conn startup values passed in or all running session, except ones marked onboot, if all is passed in.

This option is only valid for node mode (it is valid but not functional for session mode).

-W, ---no_wait

In node, discovery, or fw (firmware) mode, do not wait for a response from the target(s). This means that success will be returned if the command is able to send the login requests, whether or not they succeed. In this case, it will be up to the caller to poll for success (i.e. session creation).

-m, --mode op

specify the mode. op must be one of discovery, discoverydb, node, fw, host, iface or session.

If no other options are specified: for discovery, discoverydb and node mode, all of their respective records are displayed; for session mode, all active sessions and connections are displayed; for fw mode, all boot firmware values are displayed; for host mode, all iSCSI hosts are displayed; and for iface mode, all interfaces setup in /var/lib/iscsi/ifaces are displayed.

-n, --name=name

In node mode, specify a field name in a record. In flashnode submode of host mode, specify name of the flash node parameter.

For use with the update operator.

-o, --op=op

Specifies a database operator op. op must be one of new, delete, update, show or nonpersistent.

For iface mode, apply and applyall are also applicable.

For flashnode submode of host mode, login and logout are also applicable.

This option is valid for all modes except fw. Delete should not be used on a running session. If it is iscsiadm will stop the session and then delete the record.

An op of new creates a new database record for a given object. In node mode, the recid is the target name and portal (IP:port). In iface mode, the recid is the iface name. In discovery mode, the recid is the portal and discovery type.

In session mode, the new operation logs in a new session using the same node database and iface information as the specified session.

In discovery mode, if the recid and new operation is passed in, but the --discover argument is not passed in, then iscsiadm will only create a discovery record (it will not perform discovery). If the --discover argument is passed in with the portal and discovery type, then iscsiadm will create the discovery record if needed, and it will create records for portals returned by the target that do not yet have a node DB record.

Setting op to delete deletes the specified recid. In discovery mode, if iscsiadm is performing discovery, it will delete records for portals that are no longer returned.

Setting op to update will update the recid with name to the specified value. In discovery mode, if iscsiadm is performing discovery the recid, name and value arguments are not needed. The update operation will operate on the portals returned by the target, and will update the node records with information from the configuration file and command line.

The op value of show is the default behaviour for node, discovery and iface mode. It is also used when there are no commands passed into session mode and a running sid is passed in. If name and value are passed in, they are currently ignored in show mode.

An op value of nonpersistent instructs iscsiadm to not manipulate the node DB.

An op value of apply will cause the network settings to take effect on the specified iface.

An op value of applyall will cause the network settings to take effect on all the ifaces whose MAC address or host number matches that of the specific host.

An op value of login will log into the specified flash node entry.

An op value of logout does the logout from the given flash node entry.

-p, --portal=ip[:port]

Use target portal with IP address ip and port port. If port is not passed in the default value of 3260 is used.

IPv6 addresses can be specified as [ddd.ddd.ddd.ddd]:port or ddd.ddd.ddd.ddd.

Hostnames can also be used for the ip argument.

This option is only valid for discovery, or for node operations with the new operator.

This should be used along with --target in node mode, to specify what the open-iscsi documents refer to as a node or node record. Note: open-iscsi's use of the word node, does not match the iSCSI RFC's iSCSI Node term.

-P, --print=printlevel

If in node mode print nodes in tree format. If in session mode print sessions in tree format. If in discovery mode print the nodes in tree format.

-T, --targetname=targetname

Use target targetname.

This should be used along with --portal in node mode, to specify what the open-iscsi documents refer to as a node or node record. Note: open-iscsi's use of the word node, does not match the iSCSI RFC's iSCSI Node term.

-r, --sid=sid | sysfsdir

Use session ID sid. The session ID of a session can be found from running iscsiadm in session mode with the --info argument.

Instead of a session ID, a sysfs path containing the session can be used. For example using one of the following: /sys/devices/platform/hostH/sessionS/targetH:B:I/H:B:I:L, /sys/devices/platform/hostH/sessionS/targetH:B:I, or /sys/devices/platform/hostH/sessionS, for the sysfsdir argument would result in the session with session ID S to be used.

sid | sysfsdir is only required for session mode.

-R, --rescan

In session mode, if sid is also passed in, rescan the session. If no sid has been passed in rescan all running sessions.

In node mode, rescan a session running through the target, portal, iface tuple passed in.

-s, --stats

Display session statistics. This option when used with host mode, displays host statistics.

-S, --show

When displaying records, do not hide masked values, such as the CHAP secret (password).

This option is only valid for node and session mode.

-t, --type=type

type must be sendtargets (or abbreviated as st), isns (if enabled), or fw. See the DISCOVERY TYPES section.

This option is only valid for discovery mode.

-u, --logout

Logout for the specified record.

This option is only valid for node and session mode.

-U, --logoutall=[all,manual,automatic|onboot]

Logout of all sessions with the node or conn startup values passed in or all running sessions, except ones marked onboot, if all is passed in.

This option is only valid for node mode (it is valid but not functional for session mode).

-v, --value=value

Specify a value for use with the update operator, or for firmware login mode.

This option is only valid for node mode and flashnode submode of host mode.

-V, --version

Display version and exit.

-x, --index=index

Specify the index of the entity to operate on.

This option is only valid for chap and flashnode submodes of host mode.

## DISCOVERY TYPES
iSCSI defines 3 discovery types: SendTargets, SLP, and iSNS. SLP is not widely supported, and not supported by this pacakge. SNS supported depends on build options, but is enabled by default.

A special discovery type called fw (for firmware) is also supported, for discovering firmware interfaces, and populating the interface database in the process.

SendTargets

A native iSCSI protocol which allows each iSCSI target to send a list of available targets to the initiator.

iSNS

iSNS (Internet Storage Name Service) records information about storage volumes within a larger network. To utilize iSNS, pass the address and optionally the port of the iSNS server to do discovery to.

fw

Firmware mode. Several NICs and systems contain a mini iSCSI initiator which can be used for boot. To get the values used for boot the fw option can be used. Doing fw discovery does not store persistent records in the node or discovery DB, because the values are stored in the system's or NIC's resource.

Performing fw discovery will print the portals, like with other discovery methods. To see other settings like CHAP values and initiator settings, like you would in node mode, run iscsiadm -m fw.

## EXIT STATUS
On success 0 is returned. On error one of the return codes below will be returned.

Commands that operate on multiple objects (sessions, records, etc), iscsiadm/iscsistart will return the first error that is encountered. iscsiadm/iscsistart will attempt to execute the operation on the objects it can. If no objects are found ISCSI_ERR_NO_OBJS_FOUND is returned.

0

ISCSI_SUCCESS - command executed successfully.

1

ISCSI_ERR - generic error code.

2

ISCSI_ERR_SESS_NOT_FOUND - session could not be found.

3

ISCSI_ERR_NOMEM - could not allocate resource for operation.

4

ISCSI_ERR_TRANS - connect problem caused operation to fail.

5

ISCSI_ERR_LOGIN - generic iSCSI login failure.

6

ISCSI_ERR_IDBM - error accessing/managing iSCSI DB.

7

ISCSI_ERR_INVAL - invalid argument.

8

ISCSI_ERR_TRANS_TIMEOUT - connection timer expired while trying to connect.

9

ISCSI_ERR_INTERNAL - generic internal iscsid/kernel failure.

10

ISCSI_ERR_LOGOUT - iSCSI logout failed.

11

ISCSI_ERR_PDU_TIMEOUT - iSCSI PDU timed out.

12

ISCSI_ERR_TRANS_NOT_FOUND - iSCSI transport module not loaded in kernel or iscsid.

13

ISCSI_ERR_ACCESS - did not have proper OS permissions to access iscsid or execute iscsiadm command.

14

ISCSI_ERR_TRANS_CAPS - transport module did not support operation.

15

ISCSI_ERR_SESS_EXISTS - session is logged in.

16

ISCSI_ERR_INVALID_MGMT_REQ - invalid IPC MGMT request.

17

ISCSI_ERR_ISNS_UNAVAILABLE - iSNS service is not supported.

18

ISCSI_ERR_ISCSID_COMM_ERR - a read/write to iscsid failed.

19

ISCSI_ERR_FATAL_LOGIN - fatal iSCSI login error.

20

ISCSI_ERR_ISCSID_NOTCONN - could not connect to iscsid.

21

ISCSI_ERR_NO_OBJS_FOUND - no records/targets/sessions/portals found to execute operation on.

22

ISCSI_ERR_SYSFS_LOOKUP - could not lookup object in sysfs.

23

ISCSI_ERR_HOST_NOT_FOUND - could not lookup host.

24

ISCSI_ERR_LOGIN_AUTH_FAILED - login failed due to authorization failure.

25

ISCSI_ERR_ISNS_QUERY - iSNS query failure.

26

ISCSI_ERR_ISNS_REG_FAILED - iSNS registration/deregistration failed.

27

ISCSI_ERR_OP_NOT_SUPP - operation not support

28

ISCSI_ERR_BUSY - device or resource in use

29

ISCSI_ERR_AGAIN - operation failed, but retrying later may succeed

30

ISCSI_ERR_UNKNOWN_DISCOVERY_TYPE - unknown discovery type

31

ISCSI_ERR_CHILD_TERMINATED - child process terminated

32

ISCSI_ERR_SESSION_NOT_CONNECTED - session likely not connected

## EXAMPLES
Discover targets at a given IP address:

sh# iscsiadm --mode discoverydb --type sendtargets --portal 192.168.1.10 --discover

Login, must use a node record id found by the discovery:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --login

Logout:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260 --logout

List node records:

sh# iscsiadm --mode node

Display all data for a given node record:

sh# iscsiadm --mode node --targetname iqn.2001-05.com.doe:test --portal 192.168.1.1:3260

List all sessions:

sh# iscsiadm --mode session

List all sessions in tree format:

sh# iscsiadm --mode session --print

## FILES
/etc/iscsi/iscsid.conf

The configuration file read by iscsid and iscsiadm on startup.

/etc/iscsi/initiatorname.iscsi

The file containing the iSCSI InitiatorName and InitiatorAlias read by iscsid and iscsiadm on startup.

/var/lib/iscsi/nodes/

This directory contains the nodes with their targets.

/var/lib/iscsi/send_targets

This directory contains the portals.

## SEE ALSO
iscsid(8)

## AUTHORS
Open-iSCSI project <http://www.open-iscsi.com/>

Alex Aizman <itn780@yahoo.com>

Dmitry Yusupov <dmitry_yus@yahoo.com>


iscsid

title: iscsid(8)

summary: Open-iSCSI daemon

text:
# iscsid(8)

## NAME
iscsid - Open-iSCSI daemon

## SYNOPSIS
iscsid [OPTION]

## DESCRIPTION
The iscsid implements the control path of iSCSI protocol, plus some management facilities. For example, the daemon could be configured to automatically re-start discovery at startup, based on the contents of persistent iSCSI database.

## OPTIONS
[-c|--config=]config-file

Read configuration from config-file rather than the default /etc/iscsi/iscsid.conf file.

[-i|--initiatorname=]iname-file

Read initiator name from iname-file rather than the default /etc/iscsi/initiatorname.iscsi file.

[-f|--foreground]

run iscsid in the foreground. Implies --no-pid-file.

[-d|--debug=]debug_level

print debugging information. Valid values for debug_level are 0 to 8.

[-u|--uid=]uid

run under user ID uid (default is the current user ID).

[-g|--gid=]gid

run under user group ID gid (default is the current user group ID).

[-n|--no-pid-file]

do not write a process ID file. Conflicts with the --pid= option.

[-p|--pid=]pid-file

write process ID to pid-file rather than the default /run/iscsid.pid. Conflicts with the --no-pid-file option.

[-h|--help]

display this help and exit

[-v|--version]

display version and exit.

## FILES
/etc/iscsi/iscsid.conf

The configuration file read by iscsid and iscsiadm on startup.

/etc/iscsi/initiatorname.iscsi

The file containing the iSCSI initiatorname and initiatoralias read by iscsid and iscsiadm on startup.

/var/lib/iscsi/nodes

Open-iSCSI persistent configuration database

## SEE ALSO
iscsiadm(8)

## AUTHORS
Open-iSCSI project <http://www.open-iscsi.com/>

Alex Aizman <itn780@yahoo.com>

Dmitry Yusupov <dmitry_yus@yahoo.com>


iscsistart

title: iscsistart(8)

summary: iSCSI boot tool

text:
# iscsistart(8)

## NAME
iscsistart - iSCSI boot tool

## SYNOPSIS
iscsistart [OPTION]

## DESCRIPTION
iscsistart will start a session using the settings passed in, or using the iBFT or Open Firmware [OF] boot information. This program should not be run to manage sessions. Its primary use is to start sessions used for iSCSI root boot.

## OPTIONS
[-c|--config=]config-file

Read configuration from config-file rather than the default /etc/iscsi/iscsid.conf file.

[-i|--initiatorname=]name

Set InitiatorName to name (Required if not using iBFT or OF)

[-t|--targetname=]name

Set TargetName to name (Required if not using iBFT or OF)

[-g|--tgpt=]N

Set target portal group tag to N (Required if not using iBFT or OF)

[-a|--address=]A.B.C.D

Set IP address to A.B.C.D (Required if not using iBFT or OF)

[-p|--port=]N

Set port to N (Optional. Default 3260)

[-u|--username=]N

Set username to N (Optional)

[-w|--password=]N

Set password to N (Optional)

[-U|-username_in=]N

Set incoming username to N (Optional)

[-W|--password_in=]N

Set incoming password to N (Optional)

[-d|--debug=]debug_level

Print debugging information

[-b|--fwparam_connect]

Create a session to the target using the iBFT or OF info

[-N|--fwparam_network]

Bring up the network as specified by iBFT or OF

[-f|--fwparam_print]

Print the iBFT or OF info to STDOUT

[-P|--param=]NAME=VALUE

Set the parameter with the name NAME to VALUE. NAME is one of the settings in the node record or iscsid.conf. Multiple params can be passed in.

[-h|--help]

Display this help and exit

[-v|--version]

Display version and exit

## SEE ALSO
iscsiadm(8)

## AUTHORS
Open-iSCSI project <http://www.open-iscsi.com/>

Mike Christie <mchristi@redhat.com>


iscsiuio

package: open-iscsi-iscsiuio

title: iscsiuio(8)

summary: iSCSI UserSpace I/O driver

text:
# iscsiuio(8)

## NAME
iscsiuio - iSCSI UserSpace I/O driver

## SYNOPSIS
iscsiuio [-d-f-v]

## DESCRIPTION
iscsiuio is the UserSpace I/O driver for the QLogic NetXtreme II BCM5706/5708/5709 series PCI/PCI-X Gigabit Ethernet Network Interface Card (NIC) and for the QLogic NetXtreme II BCM57710/57711/57712/57800/57810/57840 series PCI-E 10 Gigabit Ethernet Network Interface Card. The driver has been tested on 2.6.28 kernels and above.

Refer to the README.TXT from the driver package on how to compile and install the driver.

Refer to various Linux documentations on how to configure network protocol and address.

## PARAMETERS
There are very few parameters when running this application.

-d|--debug<debuglevel>

This is to enable debug mode where debug messages will be sent to stdout The following debug modes are supported

DEBUG 4 - Print all messages INFO 3 - Print messages needed to follow the uIP code (default)

WARN 2 - Print warning messages

ERROR 1 - Only print critical errors

-f|--foreground

This is to enable foreground mode so that this application doesn't get sent into the background.

-v|--version

This is to print the version.

-p|--pid<pidfile>

Use pidfile (default /run/iscsiuio.pid )

-h|--help

Display this help and exit.

## AUTHOR
Benjamin Li - benli@broadcom.com

Eddie Wai - eddie.wai@broadcom.com

## Maintained by
QLogic-Storage-Upstream@qlogic.com


isnsadm

package: open-isns

title: isnsadm(8)

summary: iSNS client utility

text:
# isnsadm(8)

## NAME
isnsadm - iSNS client utility

## SYNOPSIS
isnsadm [options...] --register object...

isnsadm [...] --query attr[=value]

isnsadm [...] --deregister attr=value

isnsadm [...] --list type attr=value

isnsadm [...] --dd-register attr=value

isnsadm [...] --dd-deregister dd-id attr=value

isnsadm [...] --enroll client-name attr=value

isnsadm [...] --edit-policy attr=value

## DESCRIPTION
Isnsadm is a command line utility for interacting with an iSNS server. It operates in one of several modes, which are mutually exclusive. Currently, isnsadm supports registration, query, and deregistration.

## OPTIONS
By default, isnsadm will take most of its settings from the configuration file /etc/isns/isnsadm.conf, with the exception of the following options:

--config filename, -c filename

This option overrides the default configuration file.

--debug facility, -d facility

enables debugging. Valid facilities are

socket

network send/receive

auth

authentication and security related information

message

iSNS protocol layer

state

database state

scn

SCN (state change notification) messages

esi

ESI (entity status inquiry) messages

all

all of the above

--local

makes isnsadm use a Local (aka Unix) socket when talking to the iSNS server. This can be used by the administrator to perform management tasks, such as enrolling new clients, editing access control and so on. Local mode is only available to the super user.

--server servername, -s servername

specifies the server to use (if not specified in the configuration file).

--control

makes isnsadm assume the identity of a control node. Control nodes are special in that they have more rights in accessing and modifying the database than normal storage nodes have.

When using this option, isnsadm will use the source name and DSA key specified by the Control.SourceName and Control.AuthKeyFile configuration options, respectively.

--key attr=value

This option is recognized in registration mode only, and lets you specify an object key. For a more detailed explanation, refer to section Registration mode.

--keyfile=filename

When creating a policy for a new iSNS client, isnsadm is able to generate a DSA key for the client. The public part of the key is stored in a policy object in the iSNS server's database, whereas the private portion is stored in the file specified by the keyfile option.

--help

This will print a help message and exit.

### Built-in help
Isnsadm has built-in help functions. When invoked with --help, it will print a general help message showing all supported command modes, and exit. Specific help on an individual command mode is available by invoking that mode with a single argument of help, like this:

isnsadm --register help

This will print a help message describing how to use this command mode, followed by a list of attributes this command supports and a help text describing the attribute.

### Supported attributes
Most command modes take a list of attributes as arguments on the command line. The naming and syntax of these attributes are the same for all commands modes, however certain modes support only a limited set of attributes.

Attributes are usually given as name=value pairs. Where empty (or NIL) attributes are supported, the attribute name by itself can be given.

The syntax of attribute value depends on the attribute type. For strings and numeric values, no special conventions apply, but bitfields have a special syntax described below.

The attribute name is usually preceded by the object type it applies to (such as entity), followed by a hyphen and the name itself. However, where the context clearly determines a specific object type, the prefix can be omitted. For instance, when editing a policy object using --edit-policy, it is acceptable to use node-type as shorthand for policy-node-type.

Likewise, in a query command, it is not permitted to mix attributes from different object types. Thus, the first attribute of a query string establishes a type context, so that the following two invocations are equivalent:

isnsadm --query pg-name=iqn.com.foo pg-addr=10.1.1.1 pg-port=860/tcp

isnsadm --query pg-name=iqn.com.foo addr=10.1.1.1 port=860/tcp

Isnsadm currently supports the following attributes:

Context

Attribute

iSNS tag

Aliases

Network Entity

entity-id

1

eid

entity-prot

2

entity-index

7

iSCSI Storage Node

iscsi-name

32

iscsi-node-type

33

iscsi-alias

34

iscsi-idx

36

iscsi-authmethod

42

Portal

portal-addr

16

portal-port

17

portal-name

18

portal-esi-port

20

portal-esi-interval

21

portal-idx

22

portal-scn-port

23

Portal Group

portal-group-index

52

pg-name

48

pg-addr

49

pg-port

50

pg-tag

51

pgt

pg-idx

52

Discovery Domain

dd-id

2065

dd-name

2066

dd-member-iscsi-idx

2067

dd-member-name

2068

dd-member-fc-name

2069

dd-member-portal-idx

2070

dd-member-addr

2071

dd-member-port

2072

dd-features

2078

Policy Object

policy-name

-

spi

policy-key

-

policy-entity

-

policy-node-type

-

policy-object-type

-

policy-functions

-

### Portal attributes
Portal information is conveyed by two separate attributes in iSNS; an address attribute holding the IP address, and a TCP/UDP port attribute holding the port number and an indication of the protocol to be used (TCP or UDP).

When parsing a TCP/UDP port, Open-iSNS will expect a port number, optionally followed by a slash and the protocol. Port names such as "iscsi-target" are not supported.

As a convenience, isnsadm supports a notation representing a portal as one pseudo-attribute. Separating address and port by a colon. Thus, the following two are equivalent, with the latter being the shorthand representation of the former:

addr=<address> port=<port>[/protocol]. portal=<adress>:port[/protocol]

This notation can be used in any context where an addr/port attribute pair can appear, and may be prefixed by a type name, as in pg-portal=....

When using literal IPv6 addresses, the address has to be surrounded by square brackets, otherwise the embedded colons would create ambiguity: portal=[2001:5c0:0:2::24]:860/tcp

### Bitfield attributes
Some iSNS attributes are words representing a bit field. Isnsadm displays and parses these attributes in human-readable form rather than using the numerical value. The names of the bit values are displayed by built-in help facilities. When specifying a bitfield attribute on the command line, you can combine them using the plus (+) or comma (,) character, like this:

node-type=control+initiator

### Registration mode
Registration mode is selected by using the --register option, followed by a list of one or more objects to register with the iSNS server. By default, this will create a network entity for the client (if none exists), and place the new objects inside it. Usually, you register all objects for a network entity in one operation, rather than each one separately.

Each object is specified as a type, optionally followed by a comma-separated list of attributes, such as this:

target=iqn.2005-01.org.open-iscsi.foo:disk1,alias=disk1

The following object types are currently supported:

entity=name

Tells the server to group all objects in the specified Network Entity container object. Normally, the iSNS server will automatically assign an entity name that is in line with its policies, and there is no need to specify it explicitly.

initiator[=name]

This will register an iSCSI storage node of type initiator. By default, the name is set to the iSNS source name.

This can be followed by any number of iSCSI storage node attributes.

target[=name]

This will register an iSCSI storage node of type target. By default, the name is set to the iSNS source name.

This object accepts the same set of attributes as initiator.

control[=name]

This will register an iSCSI storage node of type control. By default, the name is set to the iSNS source name. Only management nodes should be registered as control nodes, as this gives a node complete control over the iSNS database.

This object accepts the same set of attributes as initiator.

portal=[address:port/proto]

This will register a portal using the given address, port and protocol triple. If the triple is omitted, isnsadm will use the client host's IP address. If the portal is preceded by an initiator registration (on the command line), the port defaults to 860/tcp; if it is preceded by a target registration, the port defaults to 3260/tcp. For multi-homed hosts, the choice of address is implementation dependent.

This can be followed by any number of portal attributes.

pg

This will register a portal group joining the preceding portal and node. Portal groups can be used to describe the preferred portals for a given node; please refer to RFC 4171 for details.

This can be followed by any number of portal group attributes. The attribute list must specify a portal group tag (PGT) via the pgt attribute.

There are two additional command line options of interest, which are used exclusively with Registration mode. One is --replace. Normally, registration mode will add new objects to the network entity associated with the client host. If you specify --replace on the command line, the server will wipe the network entity completely, and remove all portals and storage nodes it contained. Then it will create a new network entity, and place the portals and storage nodes provided by the caller inside.

In addition, it is possible to replace just parts of a network entity. This is achieved by using the command line option --key to specify the object that should be replaced.

For instance, assume a network entity contains the portal 10.1.1.1:860, and the client's network address changed to 10.2.7.7. Then the following command will atomically update the database, replacing just the portal without touching the registered storage nodes:

isnsadm --replace --key portal=10.1.1.1:860 portal=10.2.7.7:860

The --key option recognizes only a subset of the usual attributes:

Object type

Syntax

Entity

eid=identifier

Portal

portal=address:port

iSCSI Node

iscsi-name=name

To get a list of supported attributes, invoke isnsadm --register help.

### Query mode
Query mode is selected by using the --query option. A query consists of a list of attr=value pairs. All attributes must belong to the same object type, i.e. queries that mix a Network Entity attribute with e.g. a Portal attribute will be rejected.

It is also possible to specify an attribute name without value (i.e. just attr), which will will match any object that has such an attribute, regardless of its value. This is useful when you want to query for all objects of a given type.

To obtain a list of supported attributes, invoke isnsadm --query help.

### List Mode
In this mode, isnsadm will display all objects of a given type, optionally restricted to those matching certain attribute values.

The arguments to list mode are a type name, optionally followed by one or more attr=value pairs. Only attributes pertaining to the given type are permitted; for instance, if you specify a type name of portals, only portal attributes are permitted.

Possible type names are: entities, nodes, portals, dds, ddsets, portal-groups, and policies.

Additional information is available via isnsadm --list help.

### Deregistration mode
In this mode, you can deregister objects previously registered. Only the node which registered an entity in the first place is permitted to remove it, or any of its child objects. (Control nodes are not bound by this restriction).

In deregistration mode, the argument list consists of a list of attr=value pairs. Deregistration supports the same set of attributes as query mode.

### Discovery Domain Registration
This mode allows one to register a discovery domain or to add new members to an existing discovery domain. Again, attributes are specified as a list of attr=value pairs. Only discovery domain attributes are recognized.

Note, in order to add members to an existing domain, you must specify the domain's numeric ID. The domain's symbolic name is not a valid handle when referring to a discovery domain.

### Discovery Domain Deregistration mode
In this mode, you can deregister a discoery domain previously registered. Only the node which registered a discovery domain in the first place is permitted to remove it, or any of its members. (Control nodes are not bound by this restriction).

In Discovery Domain deregistration mode, the argument list consists of the Discovery Domain ID, followed by a list of attr=value pairs. Discovery Domain Deregistration supports the same set of attributes as query mode.

### Client Enrollment
This mode only works when the server recognizes the client as having control node capabilities, which is possible in two ways:

Invoke

isnsadm --local as super user on the host isnsd is running on. The --local options tells it to communicate with the server through the local control socket.

Invoke

isnsadm --control, which tells it to assume the identity of a control node. When given this option, isnsadm will use the source name and DSA key specified by the Control.SourceName and Control.AuthKeyFile configuration options, respectively. The server must be configured to grant this identity control node status.

To enroll a client, use the --enroll option, followed by the (source) name of the client to enroll. This string will be used as the name of the security policy the client will use to identify itself.

This is followed by a list of attribute/value pairs, where the following set of attributes is supported:

Attribute

Description

Aliases

name

Policy Name

spi

key

Client's DSA public key

entity

Assigned Entity Identifier

node-type

Permitted node type(s)

node-name

Permitted node name(s)

functions

Bitmap of permitted functions

object-type

Object access mask

The key attribute is used to specify the DSA public key that the server should use to authenticate messages from this client. You can either provide a file name; in which case isnsadm will try to read the PEM encoded public key from that file. If no key attribute is given, or when using key=gen, isnsadm will generate a DSA key. The private portion of the newly generated key will be stored in the file specified by --keyfile=filename.

The object-type attribute is used to specify which object types the client is permitted to access. This is a comma separated list of type:perm pairs, where type can be any of entity, iscsi-node, portal, portal-group, dd, ddset, and policy. The permissions can be either rw, or r.

The functions attribute can be used to restrict which functions the client is permitted to invoke. This is a bitfield, using the standard function names from RFC 4171, such as DevAttrReg, DevAttrQry, etc.

For a description of the open-isns security model and policies, please refer to the isns_config(5) manual page.

Important note: In order to generate a DSA key, you have to have a set of DSA parameters installed. By default, isnsadm expects to find them in /etc/isns/dsa.params. These parameters are created by calling isnsd --init once on the server machine. Alternatively, you can use the following command:

openssl dsaparam 1024 -out /etc/isns/dsa.params

where 1024 is the chosen DSA key size, in bits.

## EXAMPLES
If you want to use Open-iSNS in authenticated mode, you first need to initialize the server's DSA key and DSA parameters. This can be done conveniently by using

isnsd --init

This will create the server's private and public key, and place them in /etc/isns/auth_key and auth_key.pub, respectively.

The following command will create a policy object for a node named isns.control , and grant it control privileges:

isnsadm --local --keyfile=control.key --enroll isns.control \

node-type=ALL functions=ALL object-type=ALL

In the process of entrolling the client, this will generate a DSA key pair, and place the private key portion in the file control.key. This file must be installed as /etc/isns/control.key on the host you wish to use as an iSNS management station.

Next, you need to create a storage node object for the management station:

isnsadm --local --register control

On the management station, you can then enroll additional hosts:

isnsadm --control --keyfile=somehost.key --enroll iqn.2005-01.org.open-iscsi.somehost \

node-type=target+initiator

Again, this will generate a DSA key pair and store the private key portion in auth_key. Note the use of the --control option that tells isnsadm to use the identity of the control node instead of the default key and source name.

You then need to copy somehost.key to the client host and install it as /etc/isns/auth_key. Likewise, the server's public key (which resides in /etc/isns/auth_key.pub on the server) needs to be copied to the client machine, and placed in /etc/isns/server_key.pub.

By default, when a client registers a storage node (be it initiator or target) with iSNS, the client will not be able to see any other storage nodes. In order for targets to be visible to a given initiator, you need to create so-called Discovery Domains (or DDs for short).

Currently, domain membership operations require administrator privilege. Future extensions may allow iSNS clients to add themselves to one or more DDs upon registration.

To create a discovery domain, and add nodes to it, you can use

isnsadm --control --dd-register dd-name=mydomain \

member-name=iqn.org.bozo.client iqn.org.bozo.jbod ...

In order to add members to an existing DD, you have to specify the numeric domain ID - using the DD name is not sufficient, unfortunately (this is a requirement of the RFC, not an implementation issue):

isnsadm --control --dd-register dd-id=42 \

member-name=iqn.com.foo member-name=iqn.com.bar

The DD ID can be obtained by doing a query for the DD name:

isnsadm --control --query dd-name=mydomain

In management mode, you can also register and deregister nodes and portals manually, in case you want to fix up an inconsisteny in the database. For instance, this will register a node and portal on a host named client.bozo.org:

isnsadm --control --register entity=client.bozo.org \

initiator=iqn.org.bozo.client portal=191.168.7.1:860

Note that this registration explicitly specifies the network entity in which to place the new objects. If you omit this, the new objects will be placed in an entity named CONTROL, which is decidedly not what you want.

## SEE ALSO
RFC 4171, isnsd(8), isns_config(5).

## AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>


isnsd

title: isnsd(8)

summary: iSNS server daemon

text:
# isnsd(8)

## NAME
isnsd - iSNS server daemon

## SYNOPSIS
isnsd [-f] [-4] [-6] [-c filename] [-d debug-facility] [--dump-db] [--init]

## DESCRIPTION
Isnsd implements the iSNS protocol as defined in RFC 4171. iSNS is a discovery protocol for iSCSI and iFCP.

## OPTIONS
By default, isnsd will take most of its settings from the configuration file /etc/isns/isnsd.conf, with the exception of the following options:

--config filename, -c filename

This option overrides the default configuration file.

--foreground,-f

By default, isnsd will put itself into the background. By specifying this option, you can tell it to run in the foreground. Any error messages or debug output will be printed to the console rather than being sent to syslog.

-4

tells isnsd to create an IPv4 socket only. Normally, it defaults to IPv6 (which will accept both IPv4 and IPv6 connections).

-6

tells isnsd explicitly to create an IPv6 socket only. Since it defaults to IPv6 anyway, this is really a no-op.

--debug facility, -d facility

enables debugging. Valid facilities are

socket

network send/receive

auth

authentication and security related information

message

iSNS protocol layer

state

database state

scn

SCN (state change notification) messages

esi

ESI (entity status inquiry) messages

all

all of the above

--dump-db

This is a helper function that will read the database from the file system, and display it in human readable form. When using this option, isnsd will not open any sockets, and terminate immediately after display the database.

This option is intended to be used by the administrator when suspecting that the database contains bad/inconsistent information.

--init

This option will create the server's authentication key, and the required DSA parameters. The private key is stored in the file specified by the AuthKey option (usually /etc/isns/auth_key). The public portion of the key is written to same directory, with the suffix .pub appended to the key file name.

## SEE ALSO
RFC 4171, isnsadm(8), isnsdd(8), isns_config(5).

## AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>


isnsdd

title: isnsdd(8)

summary: iSNS discovery daemon

text:
# isnsdd(8)

## NAME
isnsdd - iSNS discovery daemon

## SYNOPSIS
isnsdd [-f] [-c filename] [-d debug-facility]

## DESCRIPTION
Isnsdd is a client side daemon for iSNS. It registers storage nodes and portals with the iSNS service, and refreshes these registrations in a timely manner.

The daemon also registers itself to receive SCN notifications, and processes these. It can be configured to invoke an external helper application for each status notification received. The path name of the helper application can be specified via the SCNCallout option in the configuration file.

## OPTIONS
By default, isnsd will take most of its settings from the configuration file /etc/isns/isnsdd.conf, with the addition of the following command line options:

--config filename, -c filename

This option overrides the default configuration file.

--foreground,-f

By default, isnsd will put itself into the background. By specifying this option, you can tell it to run in the foreground. Any error messages or debug output will be printed to the console rather than being sent to syslog.

--role role

This tells the discovery daemon in which capacity is should register itself with the iSNS server. Role can be either initiator, or control. The default is to register as an initiator.

Registering target nodes needs to use a different mechanism, as the iSCSI target server needs to inform the discovery daemon about each exported target separately. This is not implemented yet.

--debug facility, -d facility

enables debugging. Valid facilities are

socket

network send/receive

auth

authentication and security related information

message

iSNS protocol layer

state

database state

scn

SCN (state change notification) messages

esi

ESI (entity status inquiry) messages

all

all of the above

## SEE ALSO
RFC 4171, isnsd(8), isnsadm(8), isns_config(5).

## AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>


isnssetup

title: isnssetup(8)

text:
# isnssetup(8)

## NAME
isnssetup - a simple script to bootstrap an iSNS server, including security

## SYNOPSIS
isnssetup

## DESCRIPTION
isnssetup is a command line utility for for bootstrapping your iSNS installation. It sets up the authentication credentials, sets up the ServerAddress to be localhost, and registers the appropriate values in the iSNS database. The isnssetup script does not take any options.

Running this script performs the following steps:

•

Set ServerAddress to localhost and Security to 1 for isnsadmin.conf and isnsdd.conf.

•

Initialize security files by running isnsd --init, copying the public key to the server key, then restarting the isnsd daemon, so that it sees the new authorization files.

•

Registering the control node policy, the control node itself, and lastly registering the server policy.

Note that this script is supplied as an example, although you should be able to use it directly if you wish. You have to be root to run this script successfully.

## BUGS
This script does not take systemd into account, so you may have to modify it to get it to work on a modern system.

## SEE ALSO
RFC 4171, isnsadm(8), isnsd(8), isns_config(5).

## AUTHORS
Olaf Kirch <olaf.kirch@oracle.com>