title: strongswan_swanctl.conf(5)

summary: swanctl configuration file

text:
# strongswan_swanctl.conf(5)

## NAME
swanctl.conf - swanctl configuration file

## DESCRIPTION
swanctl.conf is the configuration file used by the swanctl(8) tool to load configurations and credentials into the strongSwan IKE daemon.

For a description of the basic file syntax, including number/time formats, or how to reference sections or split the configuration in multiple files by including other files, refer to strongswan.conf(5).

## SETTINGS
The following settings can be used to configure connections, credentials and pools.

connections

Section defining IKE connection configurations. The connections section defines IKE connection configurations, each in its own subsections. In the keyword description below, the connection is named <conn>, but an arbitrary yet unique connection name can be chosen for each connection subsection.

connections.<conn>

Section for an IKE connection named <conn>.

connections.<conn>.version [0]

IKE major version to use for connection. 1 uses IKEv1 aka ISAKMP, 2 uses IKEv2. A connection using the default of 0 accepts both IKEv1 and IKEv2 as responder, and initiates the connection actively with IKEv2.

connections.<conn>.local_addrs [%any]

Local address(es) to use for IKE communication, comma separated. Takes single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges. As initiator, the first non-range/non-subnet is used to initiate the connection from. As responder, the local destination address must match at least to one of the specified addresses, subnets or ranges.

If FQDNs are assigned they are resolved every time a configuration lookup is done. If DNS resolution times out, the lookup is delayed for that time.

connections.<conn>.remote_addrs [%any]

Remote address(es) to use for IKE communication, comma separated. Takes single IPv4/IPv6 addresses, DNS names, CIDR subnets or IP address ranges. As initiator, the first non-range/non-subnet is used to initiate the connection to. As responder, the initiator source address must match at least to one of the specified addresses, subnets or ranges.

If FQDNs are assigned they are resolved every time a configuration lookup is done. If DNS resolution times out, the lookup is delayed for that time.

To initiate a connection, at least one specific address or DNS name must be specified.

connections.<conn>.local_port [500]

Local UDP port for IKE communication. By default the port of the socket backend is used, which is usually 500. If port 500 is used, automatic IKE port floating to port 4500 is used to work around NAT issues. Using a non-default local IKE port requires support from the socket backend in use (socket-dynamic).

connections.<conn>.remote_port [500]

Remote UDP port for IKE communication. If the default of port 500 is used, automatic IKE port floating to port 4500 is used to work around NAT issues.

connections.<conn>.proposals [default]

A proposal is a set of algorithms. For non-AEAD IKE proposals, this includes an encryption algorithm, an integrity algorithm, a pseudo-random function and a key exchange method. For AEAD proposals, instead of encryption and integrity algorithms, a combined mode algorithm is used. With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven additional key exchanges may be negotiated. They can be configured by prefixing the algorithm keyword with keX_ (where X is a number between 1 and 7).

For IKEv2, multiple algorithms of the same kind can be specified in a single proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use multiple proposals to offer different algorithm combinations with IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value default forms a default proposal of supported algorithms considered safe, and is usually a good choice for interoperability.

connections.<conn>.vips []

Comma separated list of virtual IPs to request in IKEv2 configuration payloads or IKEv1 Mode Config. The wildcard addresses 0.0.0.0 and :: request an arbitrary address, specific addresses may be defined. The responder may return a different address, though, or none at all.

connections.<conn>.aggressive [no]

Enables Aggressive Mode instead of Main Mode with Identity Protection. Aggressive Mode is considered less secure, because the ID and HASH payloads are exchanged unprotected. This allows a passive attacker to snoop peer identities, and even worse, start dictionary attacks on the Preshared Key.

connections.<conn>.pull [yes]

If the default of yes is used, Mode Config works in pull mode, where the initiator actively requests a virtual IP. With no, push mode is used, where the responder pushes down a virtual IP to the initiating peer. Push mode is currently supported for IKEv1, but not in IKEv2. It is used by a few implementations only, pull mode is recommended.

connections.<conn>.dscp [000000]

Differentiated Services Field Codepoint to set on outgoing IKE packets for this connection. The value is a six digit binary encoded string specifying the Codepoint to set, as defined in RFC 2474.

connections.<conn>.encap [no]

To enforce UDP encapsulation of ESP packets, the IKE daemon can fake the NAT detection payloads. This makes the peer believe that NAT takes place on the path, forcing it to encapsulate ESP packets in UDP. Usually this is not required, but it can help to work around connectivity issues with too restrictive intermediary firewalls.

connections.<conn>.mobike [yes]

Enables MOBIKE on IKEv2 connections. MOBIKE is enabled by default on IKEv2 connections, and allows mobility of clients and multi-homing on servers by migrating active IPsec tunnels. Usually keeping MOBIKE enabled is unproblematic, as it is not used if the peer does not indicate support for it. However, due to the design of MOBIKE, IKEv2 always floats to port 4500 starting from the second exchange. Some implementations don't like this behavior, hence it can be disabled.

connections.<conn>.dpd_delay [0s]

Interval to check the liveness of a peer actively using IKEv2 INFORMATIONAL exchanges or IKEv1 R_U_THERE messages. Active DPD checking is only enforced if no IKE or ESP/AH packet has been received for the configured DPD delay.

connections.<conn>.dpd_timeout [0s]

Charon by default uses the normal retransmission mechanism and timeouts to check the liveness of a peer, as all messages are used for liveness checking. For compatibility reasons, with IKEv1 a custom interval may be specified; this option has no effect on connections using IKE2.

connections.<conn>.fragmentation [yes]

Use IKE fragmentation (proprietary IKEv1 extension or RFC 7383 IKEv2 fragmentation). Acceptable values are yes (the default), accept, force and no. If set to yes, and the peer supports it, oversized IKE messages will be sent in fragments. If set to accept, support for fragmentation is announced to the peer but the daemon does not send its own messages in fragments. If set to force (only supported for IKEv1) the initial IKE message will already be fragmented if required. Finally, setting the option to no will disable announcing support for this feature. Note that fragmented IKE messages sent by a peer are always accepted irrespective of the value of this option (even when set to no).

connections.<conn>.childless [allow]

Use childless IKE_SA initiation (RFC 6023) for IKEv2, with the first CHILD_SA created with a separate CREATE_CHILD_SA exchange (e.g. to use an independent key exchange for all CHILD_SAs). Acceptable values are allow (the default), prefer, force and never. If set to allow, responders will accept childless IKE_SAs (as indicated via notify in the IKE_SA_INIT response) while initiators continue to create regular IKE_SAs with the first CHILD_SA created during IKE_AUTH, unless the IKE_SA is initiated explicitly without any children (which will fail if the responder does not support or has disabled this extension). The effect of prefer is the same as allow on responders, but as initiator a childless IKE_SA is initiated if the responder supports it. If set to force, only childless initiation is accepted in either role. Finally, setting the option to never disables support for childless IKE_SAs as responder.

connections.<conn>.send_certreq [yes]

Send certificate request payloads to offer trusted root CA certificates to the peer. Certificate requests help the peer to choose an appropriate certificate/private key for authentication and are enabled by default. Disabling certificate requests can be useful if too many trusted root CA certificates are installed, as each certificate request increases the size of the initial IKE packets.

connections.<conn>.send_cert [ifasked]

Send certificate payloads when using certificate authentication. With the default of ifasked the daemon sends certificate payloads only if certificate requests have been received. never disables sending of certificate payloads altogether, always causes certificate payloads to be sent unconditionally whenever certificate authentication is used.

connections.<conn>.ocsp [reply]

Send OCSP status requests in certificate request payloads and/or send OCSP status response in certificate payloads when using certificate authentication. With the default of reply the daemon sends OCSP status responses in certificate payloads if an OCSP status request has been received in a certificate request, never disables sending of OCSP status requests and responses altogether, request causes OCSP status requests in certificate request payloads to be sent whenever certificate authentication is used, both combines reply and request.

connections.<conn>.ppk_id []

String identifying the Postquantum Preshared Key (PPK) to be used.

connections.<conn>.ppk_required [no]

Whether a Postquantum Preshared Key (PPK) is required for this connection.

connections.<conn>.keyingtries [1]

Number of retransmission sequences to perform during initial connect. Instead of giving up initiation after the first retransmission sequence with the default value of 1, additional sequences may be started according to the configured value. A value of 0 initiates a new sequence until the connection establishes or fails with a permanent error.

connections.<conn>.unique [no]

Connection uniqueness policy to enforce. To avoid multiple connections from the same user, a uniqueness policy can be enforced. The value never does never enforce such a policy, even if a peer included INITIAL_CONTACT notification messages, whereas no replaces existing connections for the same identity if a new one has the INITIAL_CONTACT notify. keep rejects new connection attempts if the same user already has an active connection, replace deletes any existing connection if a new one for the same user gets established. To compare connections for uniqueness, the remote IKE identity is used. If EAP or XAuth authentication is involved, the EAP-Identity or XAuth username is used to enforce the uniqueness policy instead.

On initiators this setting specifies whether an INITIAL_CONTACT notify is sent during IKE_AUTH if no existing connection is found with the remote peer (determined by the identities of the first authentication round). Unless set to never the client will send a notify.

connections.<conn>.reauth_time [0s]

Time to schedule IKE reauthentication. IKE reauthentication recreates the IKE/ISAKMP SA from scratch and re-evaluates the credentials. In asymmetric configurations (with EAP or configuration payloads) it might not be possible to actively reauthenticate as responder. The IKEv2 reauthentication lifetime negotiation can instruct the client to perform reauthentication. Reauthentication is disabled by default. Enabling it can usually result in short connection interruptions, even when using make-before-break reauthentication, which is now the default. However, they are significantly shorter than when using the legacy break-before-make approach.

connections.<conn>.rekey_time [4h]

IKE rekeying refreshes key material using a Diffie-Hellman exchange, but does not re-check associated credentials. It is supported in IKEv2 only, IKEv1 performs a reauthentication procedure instead. With the default value IKE rekeying is scheduled every 4 hours, minus the configured rand_time. If a reauth_time is configured, rekey_time defaults to zero disabling rekeying; explicitly set both to enforce rekeying and reauthentication.

connections.<conn>.over_time [10% of rekey_time/reauth_time]

Hard IKE_SA lifetime if rekey/reauth does not complete, as time. To avoid having an IKE/ISAKMP kept alive if IKE reauthentication or rekeying fails perpetually, a maximum hard lifetime may be specified. If the IKE_SA fails to rekey or reauthenticate within the specified time, the IKE_SA gets closed. In contrast to CHILD_SA rekeying, over_time is relative in time to the rekey_time and reauth_time values, as it applies to both.

The default is 10% of the longer of rekey_time and reauth_time.

connections.<conn>.rand_time [over_time]

Time range from which to choose a random value to subtract from rekey/reauth times. To avoid having both peers initiating the rekey/reauth procedure simultaneously, a random time gets subtracted from the rekey/reauth times. The default is equal to the configured over_time.

connections.<conn>.pools []

Comma separated list of named IP pools to allocate virtual IP addresses and other configuration attributes from. Each name references a pool by name from either the pools section or an external pool.

connections.<conn>.if_id_in [0]

XFRM interface ID set on inbound policies/SA, can be overridden by child config, see there for details. The special value %unique allocates a unique interface ID per IKE_SA, which is inherited by all its CHILD_SAs (unless overridden there), beyond that the value %unique-dir assigns a different unique interface ID for each direction (in/out).

connections.<conn>.if_id_out [0]

XFRM interface ID set on outbound policies/SA, can be overridden by child config, see there for details. The special value %unique allocates a unique interface ID per IKE_SA, which is inherited by all its CHILD_SAs (unless overridden there), beyond that the value %unique-dir assigns a different unique interface ID for each direction (in/out).

connections.<conn>.mediation [no]

Whether this connection is a mediation connection, that is, whether this connection is used to mediate other connections using the IKEv2 Mediation Extension. Mediation connections create no CHILD_SA.

connections.<conn>.mediated_by []

The name of the connection to mediate this connection through. If given, the connection will be mediated through the named mediation connection. The mediation connection must have mediation enabled.

connections.<conn>.mediation_peer []

Identity under which the peer is registered at the mediation server, that is, the IKE identity the other end of this connection uses as its local identity on its connection to the mediation server. This is the identity we request the mediation server to mediate us with. Only relevant on connections that set mediated_by. If it is not given, the remote IKE identity of the first authentication round of this connection will be used.

connections.<conn>.local<suffix>

Section for a local authentication round. A local authentication round defines the rules how authentication is performed for the local peer. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1 XAuth. Each round is defined in a section having local as prefix, and an optional unique suffix. To define a single authentication round, the suffix may be omitted.

connections.<conn>.local<suffix>.round [0]

Optional numeric identifier by which authentication rounds are sorted. If not specified rounds are ordered by their position in the config file/VICI message.

connections.<conn>.local<suffix>.certs []

Comma separated list of certificate candidates to use for authentication. The certificates may use a relative path from the swanctl x509 directory or an absolute path. The certificate used for authentication is selected based on the received certificate request payloads. If no appropriate CA can be located, the first certificate is used.

connections.<conn>.local<suffix>.cert<suffix> []

Section for a certificate candidate to use for authentication. Certificates in certs are transmitted as binary blobs, these sections offer more flexibility.

connections.<conn>.local<suffix>.cert<suffix>.file []

Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by it. Configure either this or handle, but not both, in one section.

connections.<conn>.local<suffix>.cert<suffix>.handle []

Hex-encoded CKA_ID of the certificate on a token. Configure either this or file, but not both, in one section.

connections.<conn>.local<suffix>.cert<suffix>.slot []

Optional slot number of the token that stores the certificate.

connections.<conn>.local<suffix>.cert<suffix>.module []

Optional PKCS#11 module name.

connections.<conn>.local<suffix>.pubkeys []

Comma separated list of raw public key candidates to use for authentication. The public keys may use a relative path from the swanctl pubkey directory or an absolute path. Even though multiple local public keys could be defined in principle, only the first public key in the list is used for authentication.

connections.<conn>.local<suffix>.auth [pubkey]

Authentication to perform locally. pubkey uses public key authentication using a private key associated to a usable certificate. psk uses pre-shared key authentication. The IKEv1 specific xauth is used for XAuth or Hybrid authentication, while the IKEv2 specific eap keyword defines EAP authentication. For xauth, a specific backend name may be appended, separated by a dash. The appropriate xauth backend is selected to perform the XAuth exchange. For traditional XAuth, the xauth method is usually defined in the second authentication round following an initial pubkey (or psk) round. Using xauth in the first round performs Hybrid Mode client authentication.

For eap, a specific EAP method name may be appended, separated by a dash. An EAP module implementing the appropriate method is selected to perform the EAP conversation.

If both peers support RFC 7427 ("Signature Authentication in IKEv2") specific hash algorithms to be used during IKEv2 authentication may be configured. To do so use ike: followed by a trust chain signature scheme constraint (see description of the remote section's auth keyword). For example, with ike:pubkey-sha384-sha256 a public key signature scheme with either SHA-384 or SHA-256 would get used for authentication, in that order and depending on the hash algorithms supported by the peer. If no specific hash algorithms are configured, the default is to prefer an algorithm that matches or exceeds the strength of the signature key. If no constraints with ike: prefix are configured any signature scheme constraint (without ike: prefix) will also apply to IKEv2 authentication, unless this is disabled in strongswan.conf(5). To use RSASSA-PSS signatures use rsa/pss instead of pubkey or rsa as in e.g. ike:rsa/pss-sha256. If pubkey or rsa constraints are configured RSASSA-PSS signatures will only be used if enabled in strongswan.conf(5).

connections.<conn>.local<suffix>.id []

IKE identity to use for authentication round. When using certificate authentication, the IKE identity must be contained in the certificate, either as subject or as subjectAltName. The identity can be an IP address, a fully-qualified domain name, an email address or a Distinguished Name for which the ID type is determined automatically and the string is converted to the appropriate encoding. To enforce a specific identity type, a prefix may be used, followed by a colon (:). If the number sign (#) follows the colon, the remaining data is interpreted as hex encoding, otherwise the string is used as-is as the identification data. Note that this implies that no conversion is performed for non-string identities. For example, ipv4:10.0.0.1 does not create a valid ID_IPV4_ADDR IKE identity, as it does not get converted to binary 0x0a000001. Instead, one could use ipv4:#0a000001 to get a valid identity, but just using the implicit type with automatic conversion is usually simpler. The same applies to the ASN1 encoded types. The following prefixes are known: ipv4, ipv6, rfc822, email, userfqdn, fqdn, dns, asn1dn, asn1gn and keyid. Custom type prefixes may be specified by surrounding the numerical type value by curly brackets.

connections.<conn>.local<suffix>.eap_id [id]

Client EAP-Identity to use in EAP-Identity exchange and the EAP method.

connections.<conn>.local<suffix>.aaa_id [remote-id]

Server side EAP-Identity to expect in the EAP method. Some EAP methods, such as EAP-TLS, use an identity for the server to perform mutual authentication. This identity may differ from the IKE identity, especially when EAP authentication is delegated from the IKE responder to an AAA backend. For EAP-(T)TLS, this defines the identity for which the server must provide a certificate in the TLS exchange.

connections.<conn>.local<suffix>.xauth_id [id]

Client XAuth username used in the XAuth exchange.

connections.<conn>.remote<suffix>

Section for a remote authentication round. A remote authentication round defines the constraints how the peers must authenticate to use this connection. Multiple rounds may be defined to use IKEv2 RFC 4739 Multiple Authentication or IKEv1 XAuth. Each round is defined in a section having remote as prefix, and an optional unique suffix. To define a single authentication round, the suffix may be omitted.

connections.<conn>.remote<suffix>.round [0]

Optional numeric identifier by which authentication rounds are sorted. If not specified rounds are ordered by their position in the config file/VICI message.

connections.<conn>.remote<suffix>.id [%any]

IKE identity to expect for authentication round. Refer to the local section's id keyword for details. It's possible to use wildcards to match remote identities (e.g. *@strongswan.org, *.strongswan.org, or C=CH,O=strongSwan,CN=*). Connections with exact matches are preferred. When using distinguished names with wildcards, the charon.rdn_matching option in strongswan.conf(5) specifies how RDNs are matched.

Extended POSIX regular expressions are also supported for remote identity matching. They must start with an explicit type prefix, followed by a caret character ('^'), and end with a dollar sign ('$') to indicate an anchored pattern. Make sure to escape backslash characters when configuring identities in double quotes. Supported types are rfc822, email, userfqdn, fqdn, dns, and asn1dn. While regular expressions are always matched against the string representation of other identities, the type must match as well. The matching is performed case insensitive. Examples: email:^(moon|sun)@strongswan\.org$, fqdn:^vpn[0-9]+\.strongswan\.org$, "asn1dn:^.*CN=.+\\.strongswan\\.org$".

connections.<conn>.remote<suffix>.eap_id [id]

Use EAP-Identity method to request an identity from the client to match against and use during EAP authentication. There is currently no "best" match, configs are matched in the order they are loaded. Wildcards and regular expressions are supported, refer to the id keyword for details.

connections.<conn>.remote<suffix>.groups []

Comma separated authorization group memberships to require. The peer must prove membership to at least one of the specified groups. Group membership can be certified by different means, for example by appropriate Attribute Certificates or by an AAA backend involved in the authentication.

connections.<conn>.remote<suffix>.cert_policy []

Comma separated list of certificate policy OIDs the peer's certificate must have. OIDs are specified using the numerical dotted representation.

connections.<conn>.remote<suffix>.certs []

Comma separated list of certificates to accept for authentication. The certificates may use a relative path from the swanctl x509 directory or an absolute path.

connections.<conn>.remote<suffix>.cert<suffix> []

Section for a certificate to accept for authentication. Certificates in certs are transmitted as binary blobs, these sections offer more flexibility.

connections.<conn>.remote<suffix>.cert<suffix>.file []

Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by it. Configure either this or handle, but not both, in one section.

connections.<conn>.remote<suffix>.cert<suffix>.handle []

Hex-encoded CKA_ID of the certificate on a token. Configure either this or file, but not both, in one section.

connections.<conn>.remote<suffix>.cert<suffix>.slot []

Optional slot number of the token that stores the certificate.

connections.<conn>.remote<suffix>.cert<suffix>.module []

Optional PKCS#11 module name.

connections.<conn>.remote<suffix>.cacerts []

Comma separated list of CA certificates to accept for authentication. The certificates may use a relative path from the swanctl x509ca directory or an absolute path.

connections.<conn>.remote<suffix>.cacert<suffix> []

Section for a CA certificate to accept for authentication. Certificates in cacerts are transmitted as binary blobs, these sections offer more flexibility.

connections.<conn>.remote<suffix>.cacert<suffix>.file []

Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by it. Configure either this or handle, but not both, in one section.

connections.<conn>.remote<suffix>.cacert<suffix>.handle []

Hex-encoded CKA_ID of the CA certificate on a token. Configure either this or file, but not both, in one section.

connections.<conn>.remote<suffix>.cacert<suffix>.slot []

Optional slot number of the token that stores the CA certificate.

connections.<conn>.remote<suffix>.cacert<suffix>.module []

Optional PKCS#11 module name.

connections.<conn>.remote<suffix>.ca_id []

The specified identity must be contained in one (intermediate) CA of the remote peer trustchain, either as subject or as subjectAltName. This has the same effect as specifying cacerts to force clients under a CA to specific connections; it does not require the CA certificate to be available locally, and can be received from the peer during the IKE exchange.

connections.<conn>.remote<suffix>.pubkeys []

Comma separated list of raw public keys to accept for authentication. The public keys may use a relative path from the swanctl pubkey directory or an absolute path.

connections.<conn>.remote<suffix>.revocation [relaxed]

Certificate revocation policy for CRL or OCSP revocation. A strict revocation policy fails if no revocation information is available, i.e. the certificate is not known to be unrevoked.

ifuri fails only if a CRL/OCSP URI is available, but certificate revocation checking fails, i.e. there should be revocation information available, but it could not be obtained.

The default revocation policy relaxed fails only if a certificate is revoked, i.e. it is explicitly known that it is bad.

connections.<conn>.remote<suffix>.auth [pubkey]

Authentication to expect from remote. See the local section's auth keyword description about the details of supported mechanisms. To require a trustchain public key strength for the remote side, specify the key type followed by the minimum strength in bits (for example ecdsa-384 or rsa-2048-ecdsa-256). To limit the acceptable set of hashing algorithms for trustchain validation, append hash algorithms to pubkey or a key strength definition (for example pubkey-sha256-sha512, rsa-2048-sha256-sha384-sha512 or rsa-2048-sha256-ecdsa-256-sha256-sha384). Unless disabled in strongswan.conf(5), or explicit IKEv2 signature constraints are configured (refer to the description of the local section's auth keyword for details), such key types and hash algorithms are also applied as constraints against IKEv2 signature authentication schemes used by the remote side. To require RSASSA-PSS signatures use rsa/pss instead of pubkey or rsa as in e.g. rsa/pss-sha256. If pubkey or rsa constraints are configured RSASSA-PSS signatures will only be accepted if enabled in strongswan.conf(5).

To specify trust chain constraints for EAP-(T)TLS, append a colon to the EAP method, followed by the key type/size and hash algorithm as discussed above (e.g. eap-tls:ecdsa-384-sha384).

connections.<conn>.children.<child>

CHILD_SA configuration sub-section. Each connection definition may have one or more sections in its children subsection. The section name defines the name of the CHILD_SA configuration, which must be unique within the connection.

connections.<conn>.children.<child>.ah_proposals []

AH proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For AH, this includes an integrity algorithm and an optional key exchange method. If a KE method is specified, CHILD_SA/Quick Mode rekeying and initial negotiation uses a separate key exchange using the negotiated method (refer to esp_proposals for details). With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven additional key exchanges may be negotiated. They can be configured by prefixing the algorithm keyword with keX_ (where X is a number between 1 and 7).

For IKEv2, multiple algorithms of the same kind can be specified in a single proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use multiple proposals to offer different algorithm combinations with IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value default forms a default proposal of supported algorithms considered safe, and is usually a good choice for interoperability. By default no AH proposals are included, instead ESP is proposed.

connections.<conn>.children.<child>.esp_proposals [default]

ESP proposals to offer for the CHILD_SA. A proposal is a set of algorithms. For non-AEAD ESP proposals, this includes an integrity algorithm, an encryption algorithm, an optional key exchange method and an optional Extended Sequence Number Mode indicator. For AEAD proposals, a combined mode algorithm is used instead of the separate encryption/integrity algorithms. If a key exchange method is negotiated, CHILD_SA/Quick Mode rekeying and initial negotiation use a separate key exchange using the specified method. However, for IKEv2, the keys of the CHILD_SA created implicitly with the IKE_SA will always be derived from the IKE_SA's key material. So any key exchange method specified here will only apply when the CHILD_SA is later rekeyed or is created with a separate CREATE_CHILD_SA exchange. A proposal mismatch might, therefore, not immediately be noticed when the SA is established, but may later cause rekeying to fail. If one or more key exchange methods are configured in a proposal, the key exchange can be made optional by also adding none.

With peers that support multiple IKEv2 key exchanges (RFC 9370), up to seven additional key exchanges may be negotiated. They can be configured by prefixing the algorithm keyword with keX_ (where X is a number between 1 and 7). Additional key exchanges can be made optional by adding keX_none to a proposal.

Extended Sequence Number support may be indicated with the esn and noesn values, both may be included to indicate support for both modes. If omitted, noesn is assumed.

For IKEv2, multiple algorithms of the same kind can be specified in a single proposal, from which one gets selected. For IKEv1, only one algorithm per kind is allowed per proposal, more algorithms get implicitly stripped. Use multiple proposals to offer different algorithm combinations with IKEv1.

Algorithm keywords get separated using dashes. Multiple proposals may be separated by commas. The special value default forms a default proposal of supported algorithms considered safe, and is usually a good choice for interoperability. If no algorithms are specified for AH nor ESP, the default set of algorithms for ESP is included.

connections.<conn>.children.<child>.sha256_96 [no]

HMAC-SHA-256 is used with 128-bit truncation with IPsec. For compatibility with implementations that incorrectly use 96-bit truncation this option may be enabled to configure the shorter truncation length in the kernel. This is not negotiated, so this only works with peers that use the incorrect truncation length (or have this option enabled).

connections.<conn>.children.<child>.local_ts [dynamic]

Comma separated list of local traffic selectors to include in CHILD_SA. Each selector is a CIDR subnet definition, followed by an optional proto/port selector. The special value dynamic may be used instead of a subnet definition, which gets replaced by the tunnel outer address or the virtual IP, if negotiated. This is the default. A protocol/port selector is surrounded by opening and closing square brackets. Between these brackets, a numeric or getservent(3) protocol name may be specified. After the optional protocol restriction, an optional port restriction may be specified, separated by a slash. The port restriction may be numeric, a getservent(3) service name, or the special value opaque for RFC 4301 OPAQUE selectors. Port ranges may be specified as well, none of the kernel backends currently support port ranges, though. If the protocol is icmp or ipv6-icmp, the port is interpreted as ICMP message type if it is less than 256 or as type and code if it is greater or equal to 256, with the type in the most significant 8 bits and the code in the least significant 8 bits.

When IKEv1 is used only the first selector is interpreted, except if the Cisco Unity extension plugin is used. This is due to a limitation of the IKEv1 protocol, which only allows a single pair of selectors per CHILD_SA. So to tunnel traffic matched by several pairs of selectors when using IKEv1 several children (CHILD_SAs) have to be defined that cover the selectors.

The IKE daemon uses traffic selector narrowing for IKEv1, the same way it is standardized and implemented for IKEv2. However, this may lead to problems with other implementations. To avoid that, configure identical selectors in such scenarios.

connections.<conn>.children.<child>.remote_ts [dynamic]

Comma separated list of remote selectors to include in CHILD_SA. See local_ts for a description of the selector syntax.

connections.<conn>.children.<child>.rekey_time [1h or life_time - 10%]

Time to schedule CHILD_SA rekeying. CHILD_SA rekeying refreshes key material, optionally using a Diffie-Hellman exchange if a group is specified in the proposal. To avoid rekey collisions initiated by both ends simultaneously, a value in the range of rand_time gets subtracted to form the effective soft lifetime.

If life_time is explicitly configured, rekey_time defaults to 10% less than that, otherwise, CHILD_SA rekeying is scheduled every hour, minus rand_time.

connections.<conn>.children.<child>.life_time [rekey_time + 10%]

Maximum lifetime before CHILD_SA gets closed. Usually this hard lifetime is never reached, because the CHILD_SA gets rekeyed before. If that fails for whatever reason, this limit closes the CHILD_SA. The default is 10% more than the rekey_time.

connections.<conn>.children.<child>.rand_time [life_time - rekey_time]

Time range from which to choose a random value to subtract from rekey_time. The default is the difference between life_time and rekey_time.

connections.<conn>.children.<child>.rekey_bytes [0 or life_bytes - 10%]

Number of bytes processed before initiating CHILD_SA rekeying. CHILD_SA rekeying refreshes key material, optionally using a Diffie-Hellman exchange if a group is specified in the proposal. To avoid rekey collisions initiated by both ends simultaneously, a value in the range of rand_bytes gets subtracted to form the effective soft volume limit.

Volume based CHILD_SA rekeying is disabled by default. If life_bytes is explicitly configured, rekey_bytes defaults to 10% less than that.

connections.<conn>.children.<child>.life_bytes [rekey_bytes + 10%]

Maximum bytes processed before CHILD_SA gets closed. Usually this hard volume limit is never reached, because the CHILD_SA gets rekeyed before. If that fails for whatever reason, this limit closes the CHILD_SA. The default is 10% more than rekey_bytes.

connections.<conn>.children.<child>.rand_bytes [life_bytes - rekey_bytes]

Byte range from which to choose a random value to subtract from rekey_bytes. The default is the difference between life_bytes and rekey_bytes.

connections.<conn>.children.<child>.rekey_packets [0 or life_packets - 10%]

Number of packets processed before initiating CHILD_SA rekeying. CHILD_SA rekeying refreshes key material, optionally using a Diffie-Hellman exchange if a group is specified in the proposal. To avoid rekey collisions initiated by both ends simultaneously, a value in the range of rand_packets gets subtracted to form the effective soft packet count limit.

Packet count based CHILD_SA rekeying is disabled by default. If life_packets is explicitly configured, rekey_packets defaults to 10% less than that.

connections.<conn>.children.<child>.life_packets [rekey_packets + 10%]

Maximum number of packets processed before CHILD_SA gets closed. Usually this hard packets limit is never reached, because the CHILD_SA gets rekeyed before. If that fails for whatever reason, this limit closes the CHILD_SA. The default is 10% more than rekey_bytes.

connections.<conn>.children.<child>.rand_packets [life_packets - rekey_packets]

Packet range from which to choose a random value to subtract from rekey_packets. The default is the difference between life_packets and rekey_packets.

connections.<conn>.children.<child>.updown []

Updown script to invoke on CHILD_SA up and down events.

connections.<conn>.children.<child>.hostaccess [no]

Hostaccess variable to pass to updown script.

connections.<conn>.children.<child>.mode [tunnel]

IPsec Mode to establish CHILD_SA with. tunnel negotiates the CHILD_SA in IPsec Tunnel Mode, whereas transport uses IPsec Transport Mode. transport_proxy signifying the special Mobile IPv6 Transport Proxy Mode. iptfs is IP-TFS tunnel mode with aggregation and fragmentation. beet is the Bound End to End Tunnel mixture mode, working with fixed inner addresses without the need to include them in each packet. The transport, iptfs and beet modes are subject to mode negotiation; tunnel mode is negotiated if the preferred mode is not available.

pass and drop are used to install shunt policies which explicitly bypass the defined traffic from IPsec processing or drop it, respectively.

connections.<conn>.children.<child>.policies [yes]

Whether to install IPsec policies or not. Disabling this can be useful in some scenarios e.g. MIPv6, where policies are not managed by the IKE daemon.

connections.<conn>.children.<child>.policies_fwd_out [no]

Whether to install outbound FWD IPsec policies or not. Enabling this is required in case there is a drop policy that would match and block forwarded traffic for this CHILD_SA.

connections.<conn>.children.<child>.dpd_action [clear]

Action to perform for this CHILD_SA on DPD timeout. The default clear closes the CHILD_SA and does not take further action. trap installs a trap policy, which will catch matching traffic and tries to re-negotiate the tunnel on-demand (note that this is redundant if start_action includes trap). restart immediately tries to re-negotiate the CHILD_SA under a fresh IKE_SA.

connections.<conn>.children.<child>.ipcomp [no]

Enable IPComp compression before encryption. If enabled, IKE tries to negotiate IPComp compression to compress ESP payload data prior to encryption.

connections.<conn>.children.<child>.inactivity [0s]

Timeout before closing CHILD_SA after inactivity. If no traffic has been processed in either direction for the configured timeout, the CHILD_SA gets closed due to inactivity. The default value of 0 disables inactivity checks.

connections.<conn>.children.<child>.reqid [0]

Fixed reqid to use for this CHILD_SA. This might be helpful in some scenarios, but works only if each CHILD_SA configuration is instantiated not more than once. The default of 0 uses dynamic reqids, allocated incrementally.

connections.<conn>.children.<child>.priority [0]

Optional fixed priority for IPsec policies. This could be useful to install high-priority drop policies. The default of 0 uses dynamically calculated priorities based on the size of the traffic selectors.

connections.<conn>.children.<child>.interface []

Optional interface name to restrict IPsec policies.

connections.<conn>.children.<child>.mark_in [0/0x00000000]

Netfilter mark and mask for input traffic. On Linux, Netfilter may require marks on each packet to match an SA/policy having that option set. This allows installing duplicate policies and enables Netfilter rules to select specific SAs/policies for incoming traffic. Note that inbound marks are only set on policies, by default, unless *mark_in_sa* is enabled. The special value %unique sets a unique mark on each CHILD_SA instance, beyond that the value %unique-dir assigns a different unique mark for each CHILD_SA direction (in/out). An additional mask may be appended to the mark, separated by /. The default mask if omitted is 0xffffffff.

connections.<conn>.children.<child>.mark_in_sa [no]

Whether to set *mark_in* on the inbound SA. By default, the inbound mark is only set on the inbound policy. The tuple destination address, protocol and SPI is unique and the mark is not required to find the correct SA, allowing to mark traffic after decryption instead (where more specific selectors may be used) to match different policies. Marking packets before decryption is still possible, even if no mark is set on the SA.

connections.<conn>.children.<child>.mark_out [0/0x00000000]

Netfilter mark and mask for output traffic. On Linux, Netfilter may require marks on each packet to match a policy/SA having that option set. This allows installing duplicate policies and enables Netfilter rules to select specific policies/SAs for outgoing traffic. The special value %unique sets a unique mark on each CHILD_SA instance, beyond that the value %unique-dir assigns a different unique mark for each CHILD_SA direction (in/out). An additional mask may be appended to the mark, separated by /. The default mask if omitted is 0xffffffff.

connections.<conn>.children.<child>.set_mark_in [0/0x00000000]

Netfilter mark applied to packets after the inbound IPsec SA processed them. This way it's not necessary to mark packets via Netfilter before decryption or right afterwards to match policies or process them differently (e.g. via policy routing). An additional mask may be appended to the mark, separated by /. The default mask if omitted is 0xffffffff. The special value %same uses the value (but not the mask) from mark_in as mark value, which can be fixed, %unique or %unique-dir.

Setting marks in XFRM input requires Linux 4.19 or higher.

connections.<conn>.children.<child>.set_mark_out [0/0x00000000]

Netfilter mark applied to packets after the outbound IPsec SA processed them. This allows processing ESP packets differently than the original traffic (e.g. via policy routing). An additional mask may be appended to the mark, separated by /. The default mask if omitted is 0xffffffff. The special value %same uses the value (but not the mask) from mark_out as mark value, which can be fixed, %unique or %unique-dir.

Setting marks in XFRM output is supported since Linux 4.14. Setting a mask requires at least Linux 4.19.

connections.<conn>.children.<child>.if_id_in [0]

XFRM interface ID set on inbound policies/SA. This allows installing duplicate policies/SAs and associates them with an interface with the same ID. The special value %unique sets a unique interface ID on each CHILD_SA instance, beyond that the value %unique-dir assigns a different unique interface ID for each CHILD_SA direction (in/out).

connections.<conn>.children.<child>.if_id_out [0]

XFRM interface ID set on outbound policies/SA. This allows installing duplicate policies/SAs and associates them with an interface with the same ID. The special value %unique sets a unique interface ID on each CHILD_SA instance, beyond that the value %unique-dir assigns a different unique interface ID for each CHILD_SA direction (in/out). The daemon will not install routes for CHILD_SAs that have this option set.

connections.<conn>.children.<child>.label []

Optional security label (e.g. SELinux context), IKEv2 only. Refer to label_mode for details on how labels are processed.

connections.<conn>.children.<child>.label_mode [system]

Defines the mode in which the configured security label is used. The default value of system selects selinux if strongSwan was built with SELinux support and SELinux is enabled by the kernel, otherwise, simple will be selected. If set to simple, the label will be used as is as an additional identifier/selector on the IKEv2 level when negotiating CHILD_SAs and selecting configs, labels are not installed in the kernel and received labels have to match exactly.

If set to selinux, which is only allowed if SELinux is usable on the system, the configured label is expected to be a generic context (e.g. system_u:object_r:ipsec_spd_t:s0) for which flows, whose context match it via association:polmatch, will trigger an acquire if no SA exists yet for the flow's specific context. The configured label is installed on (trap) policies, so this should generally be combined with trap in start_action. However, if the connection is initiated directly, without acquire, a childless IKE_SA is established and appropriate trap policies are installed on both ends. Labels received from peers are accepted if they match the configured label via association:polmatch.

connections.<conn>.children.<child>.tfc_padding [0]

Pads ESP packets with additional data to have a consistent ESP packet size for improved Traffic Flow Confidentiality. The padding defines the minimum size of all ESP packets sent. The default value of 0 disables TFC padding, the special value mtu adds TFC padding to create a packet size equal to the Path Maximum Transfer Unit.

connections.<conn>.children.<child>.replay_window [32]

IPsec replay window to configure for this CHILD_SA. Larger values than the default of 32 are supported using the Netlink backend only, a value of 0 disables IPsec replay protection.

connections.<conn>.children.<child>.per_cpu_sas [no]

Enable per-CPU CHILD_SAs. Requires trap in start_action.

The value encap enables a special type of UDP encapsulation (requires enabling encap for the connection if there is no NAT), where a random source port is used for each outbound per-CPU SA (the destination port for all of them remains 4500). This allows using the port for RSS if the SPI can't be used. Note that this type of behavior is not standardized and not negotiated. So regardless of whether the option is enabled, inbound per-CPU SAs with UDP-encapsulation always have the source port set to 0 as the peer's random port is unknown if it has this option enabled.

connections.<conn>.children.<child>.hw_offload [no]

Enable hardware offload for this CHILD_SA, if supported by the IPsec implementation. The values crypto or packet enforce crypto or full packet offloading and the installation will fail if the selected mode is not supported by either kernel or device. On Linux, packet also offloads policies, including trap policies. The value auto enables full packet or crypto offloading, if either is supported, but the installation does not fail otherwise.

connections.<conn>.children.<child>.copy_df [yes]

Whether to copy the DF bit to the outer IPv4 header in tunnel mode. This effectively disables Path MTU discovery (PMTUD). Controlling this behavior is not supported by all kernel interfaces.

connections.<conn>.children.<child>.copy_ecn [yes]

Whether to copy the ECN (Explicit Congestion Notification) header field to/from the outer IP header in tunnel mode. Controlling this behavior is not supported by all kernel interfaces.

connections.<conn>.children.<child>.copy_dscp [out]

Whether to copy the DSCP (Differentiated Services Field Codepoint) header field to/from the outer IP header in tunnel mode. The value out only copies the field from the inner to the outer header, the value in does the opposite and only copies the field from the outer to the inner header when decapsulating, the value yes copies the field in both directions, and the value no disables copying the field altogether. Setting this to yes or in could allow an attacker to adversely affect other traffic at the receiver, which is why the default is out. Controlling this behavior is not supported by all kernel interfaces.

connections.<conn>.children.<child>.icmp [no]

ICMP error messages, such as Destination Unreachable, Time Exceeded or Fragmentation Needed, may be generated by a host whose IP address isn't included in the negotiated traffic selectors and therefore doesn't match the IPsec policies. If this option is enabled and the kernel supports it, such packets may still be forwarded. As ICMP errors contain parts of the IP packet that triggered them, the kernel will base its decision on a reverse policy lookup using that IP header.

connections.<conn>.children.<child>.start_action [none]

Action to perform after loading the configuration. The default of none loads the connection only, which then can be manually initiated or used as a responder configuration. The value trap installs a trap policy, which triggers the tunnel as soon as matching traffic has been detected. The value start initiates the connection actively. These two modes can be combined with trap|start, to immediately initiate a connection for which trap policies have been installed.

When unloading or replacing a CHILD_SA configuration having a start_action different from none, the inverse action is performed. Configurations with start get closed, while such with trap get uninstalled (both happens for connections with trap|start).

connections.<conn>.children.<child>.close_action [none]

Action to perform after a CHILD_SA gets closed by the peer. The default of none does not take any action, trap installs a trap policy for the CHILD_SA (note that this is redundant if start_action includes trap). start tries to immediately re-create the CHILD_SA. close_action does not provide any guarantee that the CHILD_SA is kept alive. It acts on explicit close messages only, but not on negotiation failures. Use trap policies to reliably re-create failed CHILD_SAs.

secrets

Section defining secrets for IKE/EAP/XAuth authentication and private key decryption. The secrets section takes sub-sections having a specific prefix which defines the secret type. It is not recommended to define any private key decryption passphrases, as then there is no real security benefit in having encrypted keys. Either store the key unencrypted or enter the keys manually when loading credentials.

secrets.eap<suffix>

EAP secret section for a specific secret. Each EAP secret is defined in a unique section having the eap prefix. EAP secrets are used for XAuth authentication as well.

secrets.eap<suffix>.secret []

Value of the EAP/XAuth secret. It may either be an ASCII string, a hex encoded string if it has a 0x prefix or a Base64 encoded string if it has a 0s prefix in its value.

secrets.eap<suffix>.id<suffix> []

Identity the EAP/XAuth secret belongs to. Multiple unique identities may be specified, each having an id prefix, if a secret is shared between multiple users.

secrets.xauth<suffix>

XAuth secret section for a specific secret. xauth is just an alias for eap, secrets under both section prefixes are used for both EAP and XAuth authentication.

secrets.ntlm<suffix>

NTLM secret section for a specific secret. Each NTLM secret is defined in a unique section having the ntlm prefix. NTLM secrets may only be used for EAP-MSCHAPv2 authentication.

secrets.ntlm<suffix>.secret []

Value of the NTLM secret, which is the NT Hash of the actual secret, that is, MD4(UTF-16LE(secret)). The resulting 16-byte value may either be given as a hex encoded string with a 0x prefix or as a Base64 encoded string with a 0s prefix.

secrets.ntlm<suffix>.id<suffix> []

Identity the NTLM secret belongs to. Multiple unique identities may be specified, each having an id prefix, if a secret is shared between multiple users.

secrets.ike<suffix>

IKE preshared secret section for a specific secret. Each IKE PSK is defined in a unique section having the ike prefix.

secrets.ike<suffix>.secret []

Value of the IKE preshared secret. It may either be an ASCII string, a hex encoded string if it has a 0x prefix or a Base64 encoded string if it has a 0s prefix in its value.

secrets.ike<suffix>.id<suffix> []

IKE identity the IKE preshared secret belongs to. Multiple unique identities may be specified, each having an id prefix, if a secret is shared between multiple peers.

secrets.ppk<suffix>

Postquantum Preshared Key (PPK) section for a specific secret. Each PPK is defined in a unique section having the ppk prefix.

secrets.ppk<suffix>.secret []

Value of the PPK. It may either be an ASCII string, a hex encoded string if it has a 0x prefix or a Base64 encoded string if it has a 0s prefix in its value. Should have at least 256 bits of entropy for 128-bit security.

secrets.ppk<suffix>.id<suffix> []

PPK identity the PPK belongs to. Multiple unique identities may be specified, each having an id prefix, if a secret is shared between multiple peers.

secrets.private<suffix>

Private key decryption passphrase for a key in the private folder.

secrets.private<suffix>.file []

File name in the private folder for which this passphrase should be used.

secrets.private<suffix>.secret []

Value of decryption passphrase for private key.

secrets.rsa<suffix>

Private key decryption passphrase for a key in the rsa folder.

secrets.rsa<suffix>.file []

File name in the rsa folder for which this passphrase should be used.

secrets.rsa<suffix>.secret []

Value of decryption passphrase for RSA key.

secrets.ecdsa<suffix>

Private key decryption passphrase for a key in the ecdsa folder.

secrets.ecdsa<suffix>.file []

File name in the ecdsa folder for which this passphrase should be used.

secrets.ecdsa<suffix>.secret []

Value of decryption passphrase for ECDSA key.

secrets.pkcs8<suffix>

Private key decryption passphrase for a key in the pkcs8 folder.

secrets.pkcs8<suffix>.file []

File name in the pkcs8 folder for which this passphrase should be used.

secrets.pkcs8<suffix>.secret []

Value of decryption passphrase for PKCS#8 key.

secrets.pkcs12<suffix>

PKCS#12 decryption passphrase for a container in the pkcs12 folder.

secrets.pkcs12<suffix>.file []

File name in the pkcs12 folder for which this passphrase should be used.

secrets.pkcs12<suffix>.secret []

Value of decryption passphrase for PKCS#12 container.

secrets.token<suffix>

Definition for a private key that's stored on a token/smartcard.

secrets.token<suffix>.handle []

Hex-encoded CKA_ID of the private key on the token.

secrets.token<suffix>.slot []

Optional slot number to access the token.

secrets.token<suffix>.module []

Optional PKCS#11 module name to access the token.

secrets.token<suffix>.pin []

Optional PIN required to access the key on the token. If none is provided the user is prompted during an interactive --load-creds call.

pools

Section defining named pools. Named pools may be referenced by connections with the pools option to assign virtual IPs and other configuration attributes.

pools.<name>

Section defining a single pool with a unique name.

pools.<name>.addrs []

Subnet or range defining addresses allocated in pool. Accepts a single CIDR subnet defining the pool to allocate addresses from or an address range (<from>-<to>). If the address in CIDR notation is not the network ID of the subnet (e.g. 10.1.0.5/24 instead of 10.1.0.0/24), addresses below it won't be allocated to clients (they could e.g. be assigned manually to internal hosts like the VPN server itself). Pools must be unique and non-overlapping.

pools.<name>.<attr> []

Comma separated list of additional attributes of type <attr>. The attribute type may be one of dns, nbns, dhcp, netmask, server, subnet, p_cscf, split_include and split_exclude to define addresses or CIDR subnets for the corresponding attribute types. Alternatively, <attr> can be a numerical identifier, for which string attribute values are accepted as well.

authorities

Section defining attributes of certification authorities.

authorities.<name>

Section defining a certification authority with a unique name.

authorities.<name>.cacert []

CA certificate belonging to the certification authority. The certificates may use a relative path from the swanctl x509ca directory or an absolute path. Configure one of cacert, file, or handle per section.

authorities.<name>.file []

Absolute path to the certificate to load. Passed as-is to the daemon, so it must be readable by it. Configure one of cacert, file, or handle per section.

authorities.<name>.handle []

Hex-encoded CKA_ID of the CA certificate on a token. Configure one of cacert, file, or handle per section.

authorities.<name>.slot []

Optional slot number of the token that stores the CA certificate.

authorities.<name>.module []

Optional PKCS#11 module name.

authorities.<name>.crl_uris []

Comma-separated list of CRL distribution points (ldap, http, or file URI).

authorities.<name>.ocsp_uris []

Comma-separated list of OCSP URIs.

authorities.<name>.cert_uri_base []

Defines the base URI for the Hash and URL feature supported by IKEv2. Instead of exchanging complete certificates, IKEv2 allows one to send an URI that resolves to the DER encoded certificate. The certificate URIs are built by appending the SHA1 hash of the DER encoded certificates to this base URI.

## FILES

```
/etc/strongswan/swanctl/swanctl.conf       configuration file
```

## SEE ALSO
swanctl(8)


svnserve.conf

package: subversion-server-common

title: svnserve.conf(5)

text:
# svnserve.conf(5)

## NAME
svnserve.conf - Repository configuration file for svnserve

## SYNOPSIS
repository-path/conf/svnserve.conf

## DESCRIPTION
svnserve.conf controls the behavior of the svnserve daemon on a per-repository basis. It is located in the conf subdirectory of the repository.

The overall structure of the file is the same as the structure of Subversion user configuration files. At the top level are sections, which are specified by words in square brackets; inside each section are variable definitions of the form "variable = value". Lines beginning with '#' are ignored. svnserve.conf currently uses only one section named "general", and supports the following variables:

anon-access = none|read|write

Determines the access level for unauthenticated users. write access allows all repository operations. read access allows all operations except committing and changing revision properties. none access allows no access. The default level is read.

auth-access = none|read|write

Determines the access level for authenticated users, using the same access levels as above. The default level is write.

password-db = filename

Sets the location of the password database. filename may be relative to the repository conf directory. There is no default value. The password database has the same overall format as this file. It uses only one section "users"; each variable within the section is a username, and each value is a password.

authz-db = path

The authz-db option controls the location of the authorization rules for path-based access control. path may be relative to the repository conf directory. path may be a repository relative URL (^/) or absolute file:// URL to a text file in a Subversion repository. There is no default value. If you don't specify an authz-db, no path-based access control is done.

realm = realm-name

Sets the authentication realm of the repository. If two repositories have the same password database, they should have the same realm, and vice versa; this association allows clients to use a single cached password for several repositories. The default realm value is the repository's uuid.

## EXAMPLE
The following example svnserve.conf allows read access for authenticated users, no access for anonymous users, points to a passwd database in the same directory, and defines a realm name.

```
 [general]

 anon-access = none

 auth-access = read

 password-db = passwd

 realm = My First Repository
```

The file "passwd" would look like:

```
 [users]

 joeuser = joepassword

 jayrandom = randomjay
```

## SEE ALSO
svnserve(8)

branch: sisyphus


sudo.conf

package: sudo

title: sudo.conf(5)

summary: configuration for sudo front-end

text:
# sudo.conf(5)

## NAME
sudo.conf — configuration for sudo front-end

## DESCRIPTION
The sudo.conf file is used to configure the sudo front-end. It is used to configure sudo plugins, plugin-agnostic path names, debug flags, and other settings.

The sudo.conf file supports the following directives, described in detail below.

Plugin

an approval, audit, I/O logging, or security policy plugin

Path

a plugin-agnostic path

Set

a front-end setting, such as disable_coredump or group_source

Debug

debug flags to aid in debugging sudo, sudoreplay, visudo, and the sudoers plugin.

The pound sign (‘#’) is used to indicate a comment. Both the comment character and any text after it, up to the end of the line, are ignored.

Long lines can be continued with a backslash (‘\’) as the last character on the line. Leading white space is removed from the beginning of lines even when a continuation character is used.

Non-comment lines that don't begin with Plugin, Path, Debug, or Set are silently ignored.

The sudo.conf file is always parsed in the ‘C’ locale.

### Plugin configuration
sudo supports a plugin architecture for security policies and input/output logging. Third parties can develop and distribute their own policy and I/O logging plugins to work seamlessly with the sudo front-end. Plugins are dynamically loaded based on the contents of sudo.conf.

A Plugin line consists of the Plugin keyword, followed by the symbol_name and the path to the dynamic shared object that contains the plugin. The symbol_name is the name of the struct approval_plugin, struct audit_plugin, struct io_plugin, or struct policy_plugin defined by the plugin. If a plugin implements multiple plugin types, there must be a Plugin line for each unique symbol name. The path may be fully qualified or relative. If not fully qualified, it is relative to the directory specified by the plugin_dir Path setting, which defaults to /usr/lib64/sudo. In other words:

```
Plugin sudoers_policy sudoers.so
```

is equivalent to:

```
Plugin sudoers_policy /usr/lib64/sudo/sudoers.so
```

If the plugin was compiled statically into the sudo binary instead of being installed as a dynamic shared object, the path should be specified without a leading directory, as it does not actually exist in the file system. For example:

```
Plugin sudoers_policy sudoers.so
```

On AIX systems, the plugin may be either a shared object ending in ‘.so’ or an archive file containing a shared object ending in ‘.a’ with the name of the shared object in parentheses at the end.

Starting with sudo 1.8.5, any additional parameters after the path are passed as arguments to the plugin's open function. For example, to override the compile-time default sudoers file mode:

```
Plugin sudoers_policy sudoers.so sudoers_mode=0440
```

See the sudoers(5) manual for a list of supported arguments.

The same dynamic shared object may contain multiple plugins, each with a different symbol name. The file must be owned by user-ID 0 and only writable by its owner. Because of ambiguities that arise from composite policies, only a single policy plugin may be specified. This limitation does not apply to I/O plugins.

If no sudo.conf file is present, or if it contains no Plugin lines, the sudoers plugin will be used as the default security policy, for I/O logging (if enabled by the policy), and for auditing. This is equivalent to the following:

```
Plugin sudoers_policy sudoers.so
Plugin sudoers_io sudoers.so
Plugin sudoers_audit sudoers.so
```

Starting with sudo version 1.9.1, some of the logging functionality of the sudoers plugin has been moved from the policy plugin to an audit plugin. To maintain compatibility with sudo.conf files from older sudo versions, if sudoers is configured as the security policy, it will be used as an audit plugin as well. This guarantees that the logging behavior will be consistent with that of sudo versions 1.9.0 and below.

For more information on the sudo plugin architecture, see the sudo_plugin(5) manual.

### Path settings
A Path line consists of the Path keyword, followed by the name of the path to set and its value. For example:

```
Path intercept /usr/lib64/sudo/sudo_intercept.so
Path noexec /usr/lib64/sudo/sudo_noexec.so
Path askpass /usr/X11R6/bin/ssh-askpass
```

If no path name is specified, features relying on the specified setting will be disabled. Disabling Path settings is only supported in sudo version 1.8.16 and higher.

The following plugin-agnostic paths may be set in the /etc/sudo.conf file:

askpass

The fully-qualified path to a helper program used to read the user's password when no terminal is available. This may be the case when sudo is executed from a graphical (as opposed to text-based) application. The program specified by askpass should display the argument passed to it as the prompt and write the user's password to the standard output. The value of askpass may be overridden by the SUDO_ASKPASS environment variable.

devsearch

An ordered, colon-separated search path of directories to look in for device nodes. This is used when mapping the process's tty device number to a device name on systems that do not provide such a mechanism. Sudo will not recurse into sub-directories. If terminal devices may be located in a sub-directory of /dev, that path must be explicitly listed in devsearch. The default value is /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev This option is ignored on systems that support either the devname() or _ttyname_dev() functions, for example BSD, macOS and Solaris.

intercept

The path to a shared library containing wrappers for the execve(2), execl(3), execle(3), execlp(3), execv(3), execvp(3), execvpe(3), and system(3) library functions that intercepts attempts to run further commands and performs a policy check before allowing them to be executed. This is used to implement the intercept and log_subcmds functionality on systems that support LD_PRELOAD or the equivalent. The intercept path may be set to either a single fully-qualified path, or, for systems that support separate LD_PRELOAD environment variables for 32-bit and 64-bit executables, it may optionally be set to two fully-qualified paths separated by a colon (‘:’). The first path should be the 32-bit version and the second the 64-bit version. This two-path form is currently only supported on AIX and Solaris systems. The default value is /usr/lib64/sudo/sudo_intercept.so.

noexec

The path to a shared library containing wrappers for the execve(2), execl(3), execle(3), execlp(3), exect(3), execv(3), execveat(3), execvP(3), execvp(3), execvpe(3), fexecve(3), popen(3), posix_spawn(3), posix_spawnp(3), system(3), and wordexp(3) library functions that prevent the execution of further commands. This is used to implement the noexec functionality on systems that support LD_PRELOAD or the equivalent. The noexec path may be set to either a single fully-qualified path, or, for systems that support separate LD_PRELOAD environment variables for 32-bit and 64-bit executables, it may optionally be set to two fully-qualified paths separated by a colon (‘:’). The first path should be the 32-bit version and the second the 64-bit version. This two-path form is currently only supported on AIX and Solaris systems. The default value is /usr/lib64/sudo/sudo_noexec.so.

plugin_dir

The default directory to use when searching for plugins that are specified without a fully-qualified path name. The default value is /usr/lib64/sudo.

sesh

The fully-qualified path to the sesh binary. This setting is only used when sudo is built with SELinux support. The default value is /usr/lib64/sudo/sesh.

### Other settings
The sudo.conf file also supports the following front-end settings:

disable_coredump

Core dumps of sudo itself are disabled by default to prevent the disclosure of potentially sensitive information. To aid in debugging sudo crashes, you may wish to re-enable core dumps by setting “disable_coredump” to false in sudo.conf as follows:

```
Set disable_coredump false
```

All modern operating systems place restrictions on core dumps from set-user-ID processes like sudo so this option can be enabled without compromising security. To actually get a sudo core file you will likely need to enable core dumps for set-user-ID processes. On BSD and Linux systems this is accomplished in the sysctl(8) command. On Solaris, the coreadm(1m) command is used to configure core dump behavior.

This setting is only available in sudo version 1.8.4 and higher.

group_source

sudo passes the invoking user's group list to the policy and I/O plugins. On most systems, there is an upper limit to the number of groups that a user may belong to simultaneously (typically 16 for compatibility with NFS). On systems with the getconf(1) utility, running: getconf NGROUPS_MAX

will return the maximum number of groups. However, it is still possible to be a member of a larger number of groups--they simply won't be included in the group list returned by the kernel for the user. Starting with sudo version 1.8.7, if the user's kernel group list has the maximum number of entries, sudo will consult the group database directly to determine the group list. This makes it possible for the security policy to perform matching by group name even when the user is a member of more than the maximum number of groups.

The group_source setting allows the administrator to change this default behavior. Supported values for group_source are:

static

Use the static group list that the kernel returns. Retrieving the group list this way is very fast but it is subject to an upper limit as described above. It is “static” in that it does not reflect changes to the group database made after the user logs in. This was the default behavior prior to sudo 1.8.7.

dynamic

Always query the group database directly. It is “dynamic” in that changes made to the group database after the user logs in will be reflected in the group list. On some systems, querying the group database for all of a user's groups can be time consuming when querying a network-based group database. Most operating systems provide an efficient method of performing such queries. Currently, sudo supports efficient group queries on AIX, BSD, Linux, macOS, and Solaris. This is the default behavior on macOS in sudo 1.9.6 and higher.

adaptive

Only query the group database if the static group list returned by the kernel has the maximum number of entries. This is the default behavior on systems other than macOS in sudo 1.8.7 and higher.

For example, to cause sudo to only use the kernel's static list of groups for the user:

```
Set group_source static
```

This setting is only available in sudo version 1.8.7 and higher.

max_groups

The maximum number of user groups to retrieve from the group database. Values less than one or larger than 1024 will be ignored. This setting is only used when querying the group database directly. It is intended to be used on systems where it is not possible to detect when the array to be populated with group entries is not sufficiently large. By default, sudo will allocate four times the system's maximum number of groups (see above) and retry with double that number if the group database query fails. This setting is only available in sudo version 1.8.7 and higher. It should not be required in sudo versions 1.8.24 and higher and may be removed in a later release.

probe_interfaces

By default, sudo will probe the system's network interfaces and pass the IP address of each enabled interface to the policy plugin. This makes it possible for the plugin to match rules based on the IP address without having to query DNS. On Linux systems with a large number of virtual interfaces, this may take a non-negligible amount of time. If IP-based matching is not required, network interface probing can be disabled as follows:

```
Set probe_interfaces false
```

This setting is only available in sudo version 1.8.10 and higher.

### Debug settings
sudo versions 1.8.4 and higher support a flexible debugging framework that can log what sudo is doing internally if there is a problem.

A Debug line consists of the Debug keyword, followed by the name of the program, plugin, or shared object to debug, the debug file name, and a comma-separated list of debug flags. The debug flag syntax used by sudo, the sudoers plugin along with its associated programs and shared objects is subsystem@priority but a third-party plugin is free to use a different format so long as it does not include a comma (‘,’).

On AIX systems, a Debug line will match a plugin specified as either the name of an SVR4-style shared object file ending in ‘.so’, an archive file ending in ‘.a’, or an archive file ending in ‘.a’ with the name of the shared object in parentheses.

Examples:

```
Debug sudo /var/log/sudo_debug all@warn,plugin@info
```

would log all debugging statements at the warn level and higher in addition to those at the info level for the plugin subsystem.

```
Debug sudo_intercept.so /var/log/intercept_debug all@debug
```

would log all debugging statements, regardless of level, for the sudo_intercept.so shared library that implements sudo's intercept functionality on some systems.

```
Debug sudoers.so /var/log/sudoers_debug all@debug
```

would log all debugging statements, regardless of level, for the sudoers plugin. See sudoers(5) for the full list of subsystems supported by the sudoers plugin.

As of sudo 1.8.12, multiple Debug entries may be specified per program. Older versions of sudo only support a single Debug entry per program. Plugin-specific Debug entries are also supported starting with sudo 1.8.12 and are matched by either the base name of the plugin that was loaded (for example sudoers.so) or by the plugin's fully-qualified path name. Previously, the sudoers plugin shared the same Debug entry as the sudo front-end and could not be configured separately.

The following priorities are supported, in order of decreasing severity: crit, err, warn, notice, diag, info, trace, and debug. Each priority, when specified, also includes all priorities higher than it. For example, a priority of notice would include debug messages logged at notice and higher.

The priorities trace and debug also include function call tracing which logs when a function is entered and when it returns. For example, the following trace is for the get_user_groups() function located in src/sudo.c:

```
sudo[123] -> get_user_groups @ src/sudo.c:385
sudo[123] <- get_user_groups @ src/sudo.c:429 := groups=10,0,5
```

When the function is entered, indicated by a right arrow ‘->’, the program, process ID, function, source file, and line number are logged. When the function returns, indicated by a left arrow ‘<-’, the same information is logged along with the return value. In this case, the return value is a string.

The following subsystems are used by the sudo front-end:

all

matches every subsystem

args

command line argument processing

conv

user conversation

edit

sudoedit

event

event subsystem

exec

command execution

main

sudo main function

netif

network interface handling

pcomm

communication with the plugin

plugin

plugin configuration

pty

pseudo-terminal related code

selinux

SELinux-specific handling

util

utility functions

utmp

utmp handling

The sudoers(5) plugin includes support for additional subsystems.

## FILES
/etc/sudo.conf

sudo front-end configuration

## EXAMPLES

```
#
# Default /etc/sudo.conf file
#
# Sudo plugins:
#   Plugin plugin_name plugin_path plugin_options ...
#
# The plugin_path is relative to /usr/lib64/sudo unless
#   fully qualified.
# The plugin_name corresponds to a global symbol in the plugin
#   that contains the plugin interface structure.
# The plugin_options are optional.
#
# The sudoers plugin is used by default if no Plugin lines are present.
#Plugin sudoers_policy sudoers.so
#Plugin sudoers_io sudoers.so
#Plugin sudoers_audit sudoers.so

#
# Sudo askpass:
#   Path askpass /path/to/askpass
#
# An askpass helper program may be specified to provide a graphical
# password prompt for "sudo -A" support.  Sudo does not ship with its
# own askpass program but can use the OpenSSH askpass.
#
# Use the OpenSSH askpass
#Path askpass /usr/X11R6/bin/ssh-askpass
#
# Use the Gnome OpenSSH askpass
#Path askpass /usr/libexec/openssh/gnome-ssh-askpass

#
# Sudo device search path:
#   Path devsearch /dev/path1:/dev/path2:/dev
#
# A colon-separated list of paths to check when searching for a user's
# terminal device.
#
#Path devsearch /dev/pts:/dev/vt:/dev/term:/dev/zcons:/dev/pty:/dev

#
# Sudo command interception:
#   Path intercept /path/to/sudo_intercept.so
#
# Path to a shared library containing replacements for the execv(),
# execve() and fexecve() library functions, which perform a policy
# check to verify whether the command is allowed and simply return
# an error if it is not.  This is used to implement the "intercept"
# functionality on systems that support LD_PRELOAD or its equivalent.
#
# The compiled-in value is usually sufficient and should only be changed
# if you rename or move the sudo_intercept.so file.
#
#Path intercept /usr/lib64/sudo/sudo_intercept.so

#
# Sudo noexec:
#   Path noexec /path/to/sudo_noexec.so
#
# Path to a shared library containing replacements for the execv()
# family of library functions that just return an error.  This is
# used to implement the "noexec" functionality on systems that support
# LD_PRELOAD or its equivalent.
#
# The compiled-in value is usually sufficient and should only be changed
# if you rename or move the sudo_noexec.so file.
#
#Path noexec /usr/lib64/sudo/sudo_noexec.so

#
# Sudo plugin directory:
#   Path plugin_dir /path/to/plugins
#
# The default directory to use when searching for plugins that are
# specified without a fully-qualified path name.
#
#Path plugin_dir /usr/lib64/sudo

#
# Core dumps:
#   Set disable_coredump true|false
#
# By default, sudo disables core dumps while it is executing (they
# are re-enabled for the command that is run).
# To aid in debugging sudo problems, you may wish to enable core
# dumps by setting "disable_coredump" to false.
#
#Set disable_coredump false

#
# User groups:
#   Set group_source static|dynamic|adaptive
#
# Sudo passes the user's group list to the policy plugin.
# If the user is a member of the maximum number of groups (usually 16),
# sudo will query the group database directly to be sure to include
# the full list of groups.
#
# On some systems, this can be expensive so the behavior is configurable.
# The "group_source" setting has three possible values:
#   static   - use the user's list of groups returned by the kernel.
#   dynamic  - query the group database to find the list of groups.
#   adaptive - if user is in less than the maximum number of groups.
#	       use the kernel list, else query the group database.
#
#Set group_source static

#
# Sudo interface probing:
#   Set probe_interfaces true|false
#
# By default, sudo will probe the system's network interfaces and
# pass the IP address of each enabled interface to the policy plugin.
# On systems with a large number of virtual interfaces this may take
# a noticeable amount of time.
#
#Set probe_interfaces false

#
# Sudo debug files:
#   Debug program /path/to/debug_log subsystem@priority[,subsyste@priority]
#
# Sudo and related programs support logging debug information to a file.
# The program is typically sudo, sudoers.so, sudoreplay, or visudo.
#
# Subsystems vary based on the program; "all" matches all subsystems.
# Priority may be crit, err, warn, notice, diag, info, trace, or debug.
# Multiple subsystem@priority may be specified, separated by a comma.
#
#Debug sudo /var/log/sudo_debug all@debug
#Debug sudoers.so /var/log/sudoers_debug all@debug
```

## SEE ALSO
sudo_plugin(5), sudoers(5), sudo(8)

## AUTHORS
Many people have worked on sudo over the years; this version consists of code written primarily by:

Todd C. Miller

See the CONTRIBUTORS.md file in the sudo distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to sudo.

## BUGS
If you believe you have found a bug in sudo.conf, you can either file a bug report in the sudo bug database, https://bugzilla.sudo.ws/, or open an issue at https://github.com/sudo-project/sudo/issues. If you would prefer to use email, messages may be sent to the sudo-workers mailing list, https://www.sudo.ws/mailman/listinfo/sudo-workers (public) or <sudo@sudo.ws> (private).

Please do not report security vulnerabilities through public GitHub issues, Bugzilla or mailing lists. Instead, report them via email to <Todd.Miller@sudo.ws>. You may encrypt your message with PGP if you would like, using the key found at https://www.sudo.ws/dist/PGPKEYS.

## SUPPORT
Limited free support is available via the sudo-users mailing list, see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or search the archives.

## DISCLAIMER
sudo is provided “AS IS” and any express or implied warranties, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose are disclaimed. See the LICENSE.md file distributed with sudo or https://www.sudo.ws/about/license/ for complete details.