accel-ppp.conf

package: accel-ppp

title: accel-ppp.conf(5)

text:
# accel-ppp.conf(5)

## NAME
accel-ppp.conf - ACCEL-PPP VPN daemon configuration

## DESCRIPTION
accel-pppd(8) reads options from this file, usually /etc/accel-ppp.conf

Configuration file consists of sections in form:

[section1]

name1=val1

name2=val2

name3

[section2]

....

## [modules]
contains list of modules to load

log_file

This is logging target which logs messages to files. It support per-session/per-user features.

log_syslog

This is logging target which logs messages to syslog.

log_tcp

This is logging target which logs messages over TCP/IP.

log_pgsql

This is logging target which logs messages to PostgreSQL.

pptp

PPTP controlling connection handling module.

pppoe

PPPoE discovery stage handling module.

sstp

SSTP controlling connection handling module.

auth_pap

PAP authentication module.

auth_chap_md5

CHAP (md5) authentication module.

auth_mschap_v1

Microsoft CHAP (version 1) authentication module.

auth_mschap_v2

Microsoft CHAP (version 2) authentication module.

radius

RADIUS interaction module.

ippool

IPv4 address assigning module.

ipv6pool

IPv6 address assigning module.

ipv6_dhcp

IPv6 DHCP module.

sigchld

Helper module to manage child processes, required by pppd_compat

pppd_compat

This module starts pppd compatible ip-up/ip-down scripts and ip-change to handle RADIUS CoA request.

connlimit

This module limits connection rate from single source.

## [core]
Configuration of core module

log-error=path

Path to file for core module error logging.

thread-count=n

number of working threads, optimal - number of processors/cores

## [common]
Contains common params for all connection types

single-session=replace|deny

Specifies whether accel-ppp should control sessions count.

If this option is absent session count control is turned off.

If this option is replace then accel-ppp will terminate first session when second is authorized.

If this option is deny then accel-ppp will deny second session authorization.

single-session-ignore-case=0|1

Specifies whether accel-ppp should ignore the case when comparing username within single-session validation (default 0).

sid-case=upper|lower

Specifies in which case generate session identifier (default lower).

sid-source=urandom|seq

Specifies method assign session id (default urandom).

urandom Assign session id by random method

seq Assign session id by sequence method

seq-file=path

Path to file for sessions sequence number. Start sequence number may be set there (default /var/lib/accel-ppp/seq).

max-sessions=n

Specifies maximum concurrent sessions which server may processed (default 0, disabled)

max-starting=n

Specifies maximum concurrent session attempts which server may processed (default 0, disabled)

check-ip=0|1

Specifies whether accel-ppp should check if IP already assigned to other client interface (default 0). Check is global (not VRF-aware); with check-ip=1 the same IPv4/IPv6 address will be rejected even if sessions are in different VRFs/netns. With check-ip=0 overlapping addresses can be assigned (useful for isolated VRFs, but take care with overlapping pools). This setting can be overridden by module-specific 'check-ip' options (e.g., in the [ppp] section).

nl-snd-buffer=n

Specifies netlink maximum send buffer size (SO_SNDBUF option) (default 32768).

nl-rcv-buffer=n

Specifies netlink maximum receive buffer size (SO_RCVBUF option) (default 1048576).

session-timeout=n

Specifies max sessions time in seconds, after this time session will be terminated.

This timeout can be redefined with radius attribute Session-Timeout. 0 value means infinite timeout.

## [ppp]
PPP module configuration.

verbose=n

If n is not zero ppp module will produce verbose logging.

min-mtu=n

Minimum acceptable MTU. If client will try to negotiate less then specified MTU then it will be NAKed or disconnected if rejects greater MTU.

mtu=n

MTU which will be negotiated if client's MRU will be not acceptable.

mru=n

Prefered MRU.

accomp=allow|deny|n

Address/Control compression negotiation.

allow - prefere in send and don't deny in receive directions

deny - disable in both directions, default behavior

pcomp=allow|deny|n

Protocol field compression negotiation.

allow - prefere in send and don't deny in receive directions

deny - disable in both directions, default behavior

ccp=n

Disable CCP negotiation if this parameter is zero.

ccp-max-configure=n

Specifies the maximum number of CCP Configure-Request packets sent without receiving a valid Configure-Ack, Configure-Nak or Configure-Reject before assuming the peer is unable to respond (default 10).

mppe=require|prefer|deny

Specifies mppe negotiation preference.

require - ask client for mppe, if it rejects drop connection

prefer - ask client for mppe, if it rejects don't fail.

deny - deny mppe.

Default behavior - don't ask client for mppe, but allow it if client wants. Please note that RADIUS may override this option by MS-MPPE-Encryption-Policy attribute.

max-configure=n

Specifies the maximum number of LCP/IPCP Configure-Request packets sent without receiving a valid Configure-Ack, Configure-Nak or Configure-Reject before assuming the peer is unable to respond (default 10).

max-failure=n

Specifies the maximum number of LCP/IPCP Configure-Nak returned before starting to send Configure-Reject (default 10).

max-terminate=n

Specifies the maximum number of Terminate-Request packets sent without receiving a Terminate-Ack before assuming the peer has disconnected (default 2).

max-mtu=n

Specifies the absolute maximum MTU value that can be negotiated.

check-ip=0|1

Specifies whether to check if the assigned IP address is already in use by another session (overrides [common] check-ip for PPP sessions).

ipv4=deny|allow|prefer|require

Specify IPv4 (IPCP) negotiation algorithm:

deny - don't negotiate IPv4.

allow - negotiate IPv4 only if client requests.

prefer - ask client for IPv4 negotiation, don't fail if he rejects.

require - require IPv4 negotiation.

ipv6=deny|allow|prefer|require

Parameters are same as above.

ipv6-intf-id=x:x:x:x|random

Specify fixed or random interface identifier for IPv6.

ipv6-peer-intf-id=x:x:x:x|random|ipv4|calling-sid

Specify peer interface identifier for IPv6.

ipv4 - calculate interface identifier from IPv4 address, for example 192:168:0:1.

calling-sid - calculate interface identifier from Calling-Station-Id.

ipv6-accept-peer-intf-id=0|1

Specify whether to accept peer's interface identifier.

lcp-echo-interval=n

If this option is given and greater than 0 then lcp module will send echo-request every n seconds.

lcp-echo-failure=n

Specifies maximum number of echo-requests may be sent without valid echo-reply, if exceeds connection will be terminated.

lcp-echo-timeout=sec

Specifies timeout in seconds to wait for any peer activity. If this option specified it turns on adaptive lcp echo functionality and "lcp-echo-failure" is not used.

unit-cache=n

Specifies number of interfaces to keep in cache. It means that don't destroy interface after corresponding session is destroyed, instead place it to cache and use it later for new sessions repeatedly. This should reduce kernel-level interface creation/deletion rate lack.

unit-preallocate=0|1

If set to 1 then allocate ppp unit (interface) before authorization, so Nas-Port and Nas-Port-Id would be defined in Access-Request phase.

## [auth]
Contains authentication params

timeout=n

If n is not zero specifies timeout in seconds to wait for PAP, CHAP, Microsoft CHAP v1/v2 authentication.

interval=n

If n is not zero specifies timeout in seconds to restart CHAP and Microsoft CHAP v1/v2 authentication.

max-failure=n

If n is not zero specifies maximum number of CHAP and Microsoft CHAP v1/v2 authentication failures.

any-login=0|1

If set to 1 allows pass PAP, CHAP and Microsoft CHAP v1 authentication with any login.

noauth=0|1

If set to 1 skips any PPP and IPOE authentication.

challenge-name=name

Specifies challenge name for CHAP authentication.

## [ipoe]
verbose=n

If n is not zero ipoe module will produce verbose logging.

username=ifname|lua:function

Specifies how to determine username of user.

If username= ifname then interface name from which packet was arrived will be used as username.

If username= lua:username then lua function with name username will be called to construct username from dhcp packet fields.

password=username|csid|empty|<string>

Specifies how to generate password.

If password= username then password will be same as username.

If password= empty then password will be empty string.

If password= csid then password will be same as Calling-Station-Id.

Or you can specify fixed password in <string>.

session-timeout=n

Specifies max sessions time in seconds. After this time session will be terminated. May redefine with radius attribute Session-Timeout

idle-timeout=n

Specifies timeout in seconds to wait for any packets from client, after this time session will terminated if client don`t send any packet. Often used with mode=L3.

lease-time=n

Specifies lease time in seconds to be sent to dhcp client.

renew-time=n

Specifies lease renew time (option 58) in seconds to be sent to dhcp client.

rebind-time=n

Specifies lease rebind time (option 59) in seconds to be sent to dhcp client.

max-lease-time=n

Specifies max lease time in seconds, after this time session will be terminated if client won't renew it.

unit-cache=n

Specifies number of interfaces to keep in cache. It means that don't destroy interface after corresponding session is destroyed, instead place it to cache and use it later for new sessions repeatedly. This should reduce kernel-level interface creation/deletion rate lack.

l4-redirect-table=n

Specifies number of table. If L4-Redirect radius attribute is received and it's value is not 0 or '0' then accel-ppp will add following rule: ip rule add from client_ip table n

l4-redirect-ipset=name

Specifies name of ipset list. If L4-Redirect radius attribute is received and it's value is not 0 or '0' then accel-ppp will add client's ip to that ipset name.

l4-redirect-on-reject=n

If specified then if radius rejects access 'ip rule add from ip_addr table l4-redirect-table' rule will be created for time n seconds.

l4-redirect-ip-pool=name

If specified then if radius rejects access and session is DHCP then ip will be allocated from specified pool name.

gw-ip-address=x.x.x.x/mask

Specifies address to be used as server ip address if radius can assign only client address. In such case if client address is matched network and mask then specified address and mask will be used. You can specify multiple such options.

shared=0|1

Specifies default value for per-interface shared parameter.

mode=L2|L3

Specifies default value for per-interface mode parameter.

start=dhcpv4|up|auto

Specifies default value for per-interface start parameter.

ifcfg=0|1

Specifies default value for per-interface ifcfg parameter.

relay=ipv4_address

Specifies default value for per-interface relay parameter.

proxy-arp=n

Specifies default value for per-interface proxy-arp parameter.

weight=n

Specifies global weight of this server (used for load balancing)

ip-unnumbered=0|1

Specifies default value for per-interface ip-unnumbered parameter.

If ip-unnumbered=1 accel-ppp will always assign /32 mask.

Default value is 1.

agent-remote-id=string

Specifies the DCHP option 82 sub-option 2 to be inserted by the DHCP Relay.

The purpose of the sub-option is documented in section 3.2 of RFC3046.

If neither the link-selection option nor this option is present, option 82 is not inserted by the DCHP Relay Agent.

link-selection=ipv4_address

Specifies option 82 sub-option 5 as per RFC3527 to be added by dhcp relay. The value stands for the subnet to be selected by the DHCP server to associate the request to a specific subnet.

The purpose of the sub-option is documented in RFC3527.

If neither the agent-remote-id option nor this option is present, option 82 is not inserted by the DCHP Relay Agent.

interface=[re:]name[,mode=L2|L3][,shared=0|1][,start=dhcpv4|up|auto]

[,range=x.x.x.x/mask][,ifcfg=0|1] [,relay=x.x.x.x] [,giaddr=x.x.x.x] [,src=x.x.x.x] [,proxy-arp=0|1|2] [,username=ifname|lua:function] [,ipv6=0|1] [,mtu=N] [,weight=N] [,ip-unnumbered=0|1]

Specifies interface to listen dhcp or unclassified packets. You may specify multiple interface options.

If name is prefixed with re: then name is treated as regular expression.

The mode parameter specifies client connectivity mode. If mode= L2 then it means that clients are on same network where interface is. L3 means that client are behind some router.

The shared parameter specifies where interface is shared by multiple users or it is vlan-per-user.

The start parameter specifies which way session starts (up - unclassified packet).

auto - means automatically start session with username = interface name. Use it with conjunction vlan_mon.

The range parameter specifies local range of ip address to give to dhcp clients. First IP in range is router IP.

The ifcfg parameter specifies whether accel-ppp should add router IP address and route to client to interface or it is explicitly configured.

The relay parameter specifies DHCPv4 relay IP address to pass requests to. If specified giaddr is also needed.

The giaddr parameter specifies relay agent IP address.

The src parameter specifies ip address to use as source when adding route to client.

The proxy-arp parameter specifies whether accel-ppp should reply to arp requests.

local-net=x.x.x.x/mask

Specifies networks from which packets will be treated as unclassified. You may specify multiple local-net options.

proto=n

Specifies number of protocol to be used for inserted routes.

offer-delay=delay[,delay1:count1[,delay2:count2[,...]]]

Specifies delays (also in condition of connection count) to send DHCPOFFER (ms). Last delay in list may be -1 which means don't accept new connections. List must to be sorted by count key.

offer-timeout=n

Specified timeout waiting DHCP-Request from client in seconds (default 10).

vlan-mon=[re:]name[,filter]

Starts vlan monitor on specified interface (requires vlan_mon kernel module).

The filter parameter specifies list of vlans or ranges of vlans to monitor for and may be in following form:

vlan-mon=eth1,2,5,10,20-30

vlan-timeout=n

Specifies time of vlan inactivity before it will be removed in seconds (default 60). A value of 0 disables removal of inactive vlan.

vlan-name=pattern

Specifies pattern of vlan interface name. Pattern may contain following macros:

%I - name of pattern interface.

%N - number of vlan.

%P - number of vlan of parent interface.

By default vlan-name=%I.%N.

soft-terminate=0|1

Turns on soft terminate mode. Soft terminate means that session won't be terminated immediately, but when next lease renewal request will be received.

check-mac-change=0|1

If enabled accel-ppp will terminate session when detects change of mac address of client (by default it is enabled).

calling-sid=mac|ip

Specifies value of Calling-Station-Id attribute.

## [dns]
dns1=x.x.x.x

Specifies primary DNS to be sent to peer.

dns2=x.x.x.x

Specifies secondary DNS to be sent to peer.

## [wins]
wins1=x.x.x.x

Specifies primary NBNS to be sent to peer.

wins2=x.x.x.x

Specifies secondary NBNS to be sent to peer.

## [ipv6-dns]
dns=IPv6_address

Specifies IPv6 DNS to be sent to peer. You may specify up to 3 dns options.

dnssl=name

Specify DNS Search List. You may specify multiple dns and dnssl options.

## [client-ip-range]
You have to explicitly specify range of ip address from which clients can connect to server in form:

x.x.x.x/mask (for example 10.0.0.0/8)

x.x.x.x-y (for example 10.0.0.1-254)

## [pptp]
Configuration of PPTP module.

bind=x.x.x.x

If this option is given then pptp server will bind to specified IP address.

port=n

If this option is given then pptp server will bind to specified port.

verbose=n

If this option is given and n is greater of zero then pptp module will produce verbose logging.

echo-interval=n

If this option is given and greater than zero then pptp module will send echo-request every n seconds.

echo-failure=n

Specifies maximum number of echo-requests may be sent without valid echo-reply, if exceeds connection will be terminated.

timeout=n

Timeout waiting reply from client in seconds (default 5).

mppe=deny|allow|prefer|require

ifname=ifname

If this option is given ppp interface will be renamed using ifname as a template, i.e pptp%d => pptp0.

ppp-max-mtu=n

Set the maximum MTU value that can be negotiated for PPP over PPTP sessions. Default value is 1436.

session-timeout=n

Specifies max sessions time in seconds, after this time session will be terminated.

This timeout can be redefined with radius attribute Session-Timeout. 0 value means infinite timeout.

## [pppoe]
Configuration of PPPoE module.

interface=[re:]ifname[,padi-limit=n]

Specifies interface name to listen/send discovery packets. You may specify multiple interface options. If ifname is prefixed with re: then ifname is considered as regular expression. Optional padi-limit parameter specifies limit of PADI packets to reply on this interface in 1 second period.

vlan-mon=[re:]name[,filter]

Starts vlan monitor on specified interface (requires vlan_mon kernel module).

The filter parameter specifies list of vlans or ranges of vlans to monitor for and may be in following form:

vlan-mon=eth1,2,5,10,20-30

vlan-timeout=n

Specifies time of vlan inactivity before it will be removed in seconds (default 60). A value of 0 disables removal of inactive vlan.

vlan-name=pattern

Specifies pattern of vlan interface name. Pattern may contain following macros:

%I - name of pattern interface.

%N - number of vlan.

%P - number of vlan of parent interface.

By default vlan-name=%I.%N.

ac-name=ac-name

Specifies AC-Name tag value. If absent tag will not be sent.

service-name=service-name

Specifies Service-Name to respond. If absent any Service-Name is acceptable and client's Service-Name will be sent back.

accept-any-service=n

If service-name specified still will answer with service names, but accepts any service name in PADR request. Useful for scenarios, where selection of PPPoE done by client, based on service names in PADO.

accept-blank-service=n

Allow answering on blank Service-Name even if Service-Name configured. Useful when needs to allow only Service-Names described in the config and also blank Service-Name.

pado-delay=delay[,delay1:count1[,delay2:count2[,...]]]

Specifies delays (also in condition of connection count) to send PADO (ms). Last delay in list may be -1 which means don't accept new connections. List have to be sorted by count key.

mac-filter=filename,type

Specifies mac-filter filename and type, type maybe allow or deny

called-sid=ifname|mac|ifname:mac

Specifies how to represent Called-Station-ID.

ifname - Called-Station-ID will contain name of interface accepted request.

mac - Called-Station-ID will contain mac address of interface accepted request.

ifname:mac - Called-Station-Id will contain both name and mac of interface.

verbose=n

If this option is given and n is greater of zero then pppoe module will produce verbose logging.

tr101=0|1

Specifies whether to handle TR101 tags.

padi-limit=n

Specifies overall limit of PADI packets to reply in 1 second period (default 0 - unlimited). Rate of per-mac PADI packets is limited to no more than 1 packet per second.

mppe=deny|allow|prefer|require

ifname=ifname

If this option is given ppp interface will be renamed using ifname as a template, i.e pppoe%d => pppoe0.

session-timeout=n

Specifies max sessions time in seconds, after this time session will be terminated.

This timeout can be redefined with radius attribute Session-Timeout. 0 value means infinite timeout.

ip-pool=pool_name

Specifies the name of the IPv4 pool to use for allocating client addresses.

ipv6-pool=pool_name

Specifies the name of the IPv6 pool to use for allocating client addresses.

ipv6-pool-delegate=pool_name

Specifies the name of the IPv6 prefix delegation pool to use.

ifname-in-sid=0|1

If set to 1, the interface name is included in the Session ID.

sid-uppercase=0|1

If set to 1, the Session ID is generated in uppercase.

cookie-timeout=n

Specifies the timeout in seconds for the PPPoE cookie (PADO/PADR stage).

## [l2tp]
Configuration of L2TP module.

bind=x.x.x.x

Specifies IP address to bind.

port=n

Specifies port to bind.

host-name=string

This name will be sent to clients in Host-Name attribute.

hello-interval=n

Specifies interval (in seconds) to send Hello control message. Its used for keep alive connection. If peer will not respond to Hello connection will be terminated.

recv-window=n

Set the size of the local receive window. Only received messages whose sequence number is in the range [last-Nr + 1, last-Nr + recv-window] are accepted (where last-Nr is the sequence number of the last acknowledged message). Minimum value is 1, maximum is 32768, default is 16.

timeout=n

Specifies timeout (in seconds) to wait peer completes tunnel and session negotiation.

rtimeout=n

Specifies timeout (in seconds) to wait message acknowledge, if elapsed message retransmition will be performed. Timeout is multiplied by two after each retransmission. So if rtimeout is set to 1, first retransmission will occur after one second, second retransmission two seconds later, third one four seconds later, and so on, until a reply is received or the retransmit value is reached. Default value is 1.

rtimeout-cap=n

Set the maximum interval between retransmissions. The exponential backoff interval used by rtimeout will never grow above rtimeout-cap. rtimeout-cap must be higher than rtimeout and, according to RFC 2661, must be no less than 8 (though accel-ppp doesn't enforce this rule). Default value is 16.

retransmit=n

Specifies maximum number of message retransmission, if exceeds connection will be terminated.

verbose=n

If this option is given and n is greater of zero then l2tp module will produce verbose logging.

mppe=deny|allow|prefer|require

secret=string

Specifies secret to connect to server.

hide-avps=n

If this option is given and n is greater than 0, then attributes sent in L2TP packets will be hidden (for AVPs that support it).

dataseq=deny|allow|prefer|require

Specify data sequencing negotiation algorithm:

deny - don't send data packets with sequence numbers

allow - send data packets with sequence numbers if peer have requested so only

prefer - send data packets with sequence numbers and enable same for peer

require - send data packets with sequence numbers and enforce same for peer

reorder-timeout=ms

Specifies timeout (in milliseconds) to wait for out-of-order packets. If 0, don't try to reorder.

use-ephemeral-ports=0|1

Specifies if an arbitrary source port is used when replying to a tunnel establishment request. When this option is deactivated, the destination port of the incoming request (SCCRQ) is used as source port for the reply (SCCRP). Default value is 0.

ppp-max-mtu=n

Set the maximum MTU value that can be negotiated for PPP over L2TP sessions. Default value is 1420.

ifname=ifname

If this option is given ppp interface will be renamed using ifname as a template, i.e l2tp%d => l2tp0.

session-timeout=n

Specifies max sessions time in seconds, after this time session will be terminated.

This timeout can be redefined with radius attribute Session-Timeout. 0 value means infinite timeout.

avp_permissive=0|1

If set to 1, ignore the Mandatory (M) bit in unknown Attribute-Value Pairs (AVPs) instead of terminating the connection.

dir300_quirk=0|1

If set to 1, enables a workaround for D-Link DIR-300 routers that send packets with Tunnel ID 0.

ip-pool=pool_name

Specifies the name of the IPv4 pool to use for allocating client addresses.

ipv6-pool=pool_name

Specifies the name of the IPv6 pool to use for allocating client addresses.

ipv6-pool-delegate=pool_name

Specifies the name of the IPv6 prefix delegation pool to use.

## [sstp]
Configuration of SSTP module.

bind=x.x.x.x|ipv6address|unix:pathname|unix:@abstract

If this option is given then sstp server will bind to specified IP address or unix pathname/abstract socket.

port=n

If this option is given then sstp server will bind to specified port. Default is 443.

verbose=n

If this option is given and n is greater of zero then sstp module will produce verbose logging.

timeout=n

Timeout waiting reply from client in seconds. Default is 60.

hello-interval=n

If this option is given and greater than zero then sstp will send echo-request every n seconds and drop connection without a reply. Default is 60.

accept=ssl,proxy

Specifies incoming connection acceptance mode.

ssl - enable SSL/TLS support.

proxy - enable PROXY protocol 1 & 2 support.

This is useful when accel-ppp is running behind a load balancer (like HAProxy or Nginx) or a reverse proxy. It allows accel-ppp to receive the original client IP address and port instead of the proxy's IP. The extracted real client IP is then used for:

- connlimit module checks (limiting connections per source IP). - client-ip-range verification. - Calling-Station-Id attribute in RADIUS and logs.

ssl-protocol=ssl2|ssl3|tls1|tls1.1|tls1.2|tls1.3

Specifies the enabled SSL/TLS protocols supported by OpenSSL library.

ssl-dhparam=pemfile

Specifies a file with DH parameters for DHE ciphers.

ssl-ecdh-curve=string

Specifies a curves for ECDHE ciphers. Value is specified in the format understood by the OpenSSL library.

ssl-ciphers=string

Specifies the enabled ciphers. The ciphers are specified in the format understood by the OpenSSL library.

ssl-prefer-server-ciphers=n

If this option is given and n is greater of zero then server ciphers should be preferred over client ciphers. Default is 0.

ssl-pemfile=pemfile

Specifies a PEM file with the server certificate. Files that contain only the leaf certificate are still supported for backward compatibility. When the file includes the full chain, certificates must be sorted starting with the subject's certificate (actual server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root) CA. The leaf certificate (first in the file) is used to compute the initial SHA1 and SHA256 certificate hash.

ssl-keyfile=keyfile

Specifies a file with the secret key in the PEM format for sstp server. If not set, secret key will be loaded from the pemfile parameter.

cert-hash-proto=sha1,sha256

Specifies hashing methods that can be used to compute the Compound MAC in the Crypto Binding attribute. Default is sha1 and sha256 both.

cert-hash-sha1=hexstring

Given hexadecimal value overrides SHA1 hash computed from the pemfile certificate or used directly for non-ssl mode.

cert-hash-sha256=hexstring

Given hexadecimal value overrides SHA256 hash computed from the pemfile certificate or used directly for non-ssl mode.

host-name=string

If this option is given, only sstp connection to specified host and with the same TLS SNI will be allowed.

http-error=deny|allow|http[s]://host.tld[/path]

Specify http layer error behavior for non-sstp requests.

deny - reset connection without any error response.

allow - respond with http-specific status codes.

http[s]://host.tld[/path] - respond with http redirect to the specified location. If /path is not specified, requested uri will be appended automatically

Default value is allow.

ifname=ifname

If this option is given ppp interface will be renamed using ifname as a template, i.e sstp%d => sstp0.

ppp-max-mtu=n

Set the maximum MTU value that can be negotiated for PPP over SSTP sessions. Default value is 1452, maximum is 4087.

ip-pool=pool_name

Specifies the name of the IPv4 pool to use for allocating client addresses.

ipv6-pool=pool_name

Specifies the name of the IPv6 pool to use for allocating client addresses.

ipv6-pool-delegate=pool_name

Specifies the name of the IPv6 prefix delegation pool to use.

sndbuf=n

Specifies the TCP send buffer size (SO_SNDBUF) for the SSTP socket.

rcvbuf=n

Specifies the TCP receive buffer size (SO_RCVBUF) for the SSTP socket.

session-timeout=n

Specifies max sessions time in seconds, after this time session will be terminated.

This timeout can be redefined with radius attribute Session-Timeout. 0 value means infinite timeout.

## [radius]
Configuration of RADIUS module.

nas-identifier=identifier

Specifies value to send to RADIUS server in NAS-Identifier attribute and to be matched in DM/CoA requests.

nas-ip-address=x.x.x.x

Specifies value to send to RADIUS server in NAS-IP-Address attribute and to be matched in DM/CoA requests. Also DM/CoA server will bind to that address.

gw-ip-address=x.x.x.x

Specifies address to use as local address of ppp interfaces if Framed-IP-Address received from RADIUS server.

auth-server=x.x.x.x:port,secret

Specifies IP address, port and secret of authentication RADIUS server. (obsolete)

acct-server=x.x.x.x:port,secret

Specifies IP address, port and secret of accounting RADIUS server. (obsolete)

server=address,secret[,auth-port=1812][,acct-port=1813][,bind-device=][,req-limit=0][,fail-timeout=0,max-fail=0,][,weight=1][,backup]

Specifies IP address, secret, ports of RADIUS server.

bind-device - device name or VRF to bind the connection. By default, the device name is undefined.

req-limit - number of simultaneous requests to server (0 - unlimited).

fail-time - if server doesn't responds mark it as unavailable for this time (sec).

max-fail - number of unreplied requests in a row after that mark server as unavailable.

weight - specifies weight of server for multi-server configuration.

backup - mark server as backup server f.e. use this server only when all other servers are failed.

If you want to specify only authentication or accounting server then set auth-port/acct-port to zero. You may specify multiple radius servers.

dae-server=x.x.x.x:port,secret[,bind-device=] Specifies IP address, port to bind and secret for Dynamic Authorization Extension server (DM/CoA).

bind-device - device name or VRF to bind the connection. By default, the device name is undefined.

dm_coa_secret=secret(deprecated,usedae-serverinstead)

Specifies secret to use in DM/CoA communication.

acct-interim-interval=n

Specifies interval in seconds to send accounting information (may be overriden by radius Acct-Interim-Interval attribute)

acct-interim-jitter=n

Specifies absolute maximum jitter value in seconds to be applied to accounting information interval.

verbose=n

If this option is given and n is greater of zero then radius module will produce verbose logging.

interim-verbose=n

If this option is given and n is greater of zero then radius module will produce verbose logging of interim radius packets.

timeout=n

Timeout to wait response from server (sec)

max-try=n

Specifies number of tries to send Access-Request/Accounting-Request queries.

acct-timeout=n

Specifies timeout of accounting interim update.

acct-delay-time=0|1

Specifies whether radius client should include Acct-Delay-Time attribute to accounting requests (default 0).

acct-delay-start=n

Specifies delay to send accounting start packet (defaul 0).

acct-on=0|1

Specifies whether radius client should send Account-Request with Acct-Status-Type=Accounting-On on startup and Acct-Status-Type=Accounting-Off on shutdown.

attr-tunnel-type=name

Specifies custom attribute name to be used to send tunnel type (as string).

default-realm=realm

Appends specified realm to username if there was no realm already.

strip-realm=0|1

Strips realm from username, can be used along with default-realm option for realm substitution.

sid-in-auth=0|1

Specifies should accel-ppp generate and send Acct-Session-Id on Access-Request packet.

nas-port-id-in-req=0|1

Specifies should accel-ppp send NAS-Port-Id on Access-Request and Accounting-Request packets (default 1).

bind=x.x.x.x

Specifies the source IP address for outgoing RADIUS packets.

require-nas-identification=0|1

If enabled, checks that the NAS-Identifier or NAS-IP-Address in DM/CoA requests matches the server's configuration.

blast-protection=0|1

If this option is given and 1 is specified then radius module will include Message-Authenticator attribute in Access-Request packets.

## [log]
Configuration of log and log_file modules.

log-file=file

Path to file to write general log.

log-emerg=file

Path to file to write emergency messages.

log-fail-file=file

Path to file to write authentication failed session log.

log-tcp=x.x.x.x:port

Send logs to specified host.

syslog=ident[,facility]

Send logs to system logger. Facility may be: daemon, local0-local7 or numeric value.

copy=n

If this options is given and greater than zero logging engine will duplicate session log in general log. (Useful when per-session/per-user logs are not used)

per-session-dir=dir

Directory for session logs. If specified each session will be logged separately to file which name is unique session identifier.

per-user-dir=dir

Directory for user logs. If specified all sessions of same user will be logged to file which name is user name.

per-session=n

If specified and n is greater than zero each session of same user will be logger separately to directory specified by "per-user-dir" and subdirectory which name is user name and to file which name os unique session identifier.

level=n

Specifies log level which values are:

0 turn off all logging

1 log only error messages

2 log error and warning messages

3 log error, warning and minimum information messages (use this level in conjunction with verbose option of other modules if you need verbose logging)

4 log error, warning and full information messages (use this level in conjunction with verbose option of other modules if you need verbose logging)

5 log all messages including debug messages

## [log-pgsql]
Configuration of log_pgsql module.

conninfo=conninfo

Conninfo to connect to PostgreSQL server.

log-table=table

Table to send log messages. Table must contain following field:

timestamp timestamp

username text

sessionid text

msg text

## [pppd_compat]
Configuration of pppd_compat module.

ip-pre-up=file

Path to ip-pre-up script which is executed before ppp interface comes up, useful to setup firewall rules before any traffic can pass through the interface.

ip-up=file

Path to ip-up script which is executed when ppp interfaces is completely configured and started.

ip-down=file

Path to ip-down script which is executed when session is about to terminate.

ip-change=file

Path to ip-change script which is executed for RADIUS CoA handling.

radattr-prefix=prefix

Prefix of radattr files (for example /var/run/radattr, resulting files will be /var/run/radattr.pppX)

verbose=n

If specified and greater than zero pppd_module will produce verbose logging.

## [chap-secrets]
Configuration of chap-secrets module.

gw-ip-address=x.x.x.x[/mask]

Specifies address to use as local address of ppp interfaces if chap-secrets is used for IP address assignment. Mask is used for IPoE.

chap-secrets=file

Specifies alternate chap-secrets file location (default is /etc/ppp/chap-secrets).

encrypted=0|1

Specifies either chap-secrets is encrypted (read README).

username-hash=hash1[,hash2]

Specifies hash chain to calculate username hash.

hash1, hash2 are openssl known digest names (md5, sha1, etc).

## [ip-pool]
Configuration of ippool module.

gw-ip-address=x.x.x.x

Specifies single IP address to be used as local address of ppp interfaces.

shuffle=1|0

Specifies whether to shuffle initial address list.

gw=range

Specifies range of local address of ppp interfaces if form:

x.x.x.x/mask[,name=pool_name][,next=next_pool_name] (for example 10.0.0.0/8)

x.x.x.x-y[,name=pool_name][,next=next_pool_name] (for example 10.0.0.1-254)

tunnel=range

Specifies range of remote address of ppp interfaces if form:

x.x.x.x/mask[,name=pool_name][,next=next_pool_name]

x.x.x.x-y[,name=pool_name][,next=next_pool_name]

x.x.x.x/mask[,name=pool_name][,next=next_pool_name] or x.x.x.x-y[,name=pool_name][,next=next_pool_name]

Also specifies range of remote address of ppp interfaces.

You may also omit the "name=" key and use a shorthand pool name after the comma, e.g.

10.0.0.0/24,pool1

attr=attribute

Specifies which Radius attribute contains pool name.

vendor=vendor

If attribute is vendor-specific then specify vendor name in this option.

Note: overlapping ranges in different pools are not de-duplicated. If two pools cover the same address, that IP can be allocated from each pool independently. Use non-overlapping ranges (or a single pool with next= chaining) to avoid duplicate assignments.

## [ipv6-dhcp]
aftr-gw=name

Specifies the AFTR-Name option value to be returned on DHCPv6 replies upon request from the client.

## [ipv6-pool]
Configuration of ipv6pool module.

ipv6prefix/mask,prefix_len[,name=pool_name][,next=next_pool_name]

fc00:0:1::/48,64 - specifies pool of address by dividing prefix fc00:0:1::/48 to networks with 64 prefix len, e.g:

fc00:0:1:0::/64

fc00:0:1:1::/64

...

fc00:0:1:ffff::/64

delegate=ipv6prefix/mask,prefix_len[,name=pool_name][,next=next_pool_name]

Specifies range of prefixes to delegate to clients through DHCPv6 prefix delegation (rfc3633). Format is same as described above.

gw-ip6-address=ipv6address

Specifies gateway address (used only for /128 prefixes)

attr-prefix=attribute

Specifies which Radius attribute contains delegated prefix pool name.

attr-address=attribute

Specifies which Radius attribute contains stateful address pool name.

vendor=vendor

If attribute is vendor-specific then specify vendor name in this option.

## [connlimit]
This module limits connection rate from single source.

limit=count/time

Specifies acceptable rate of connections, for example limit=1/s or limit=10/m.

burst=count

timeout=n

Specifies timeout in seconds after which module doesn't check rate until burst number of connections will be arrived.

## [shaper]
This module controls shaper.

attr=name

Specifies which radius attribute contains rate information. Default - Filter-ID.

attr-up=name

attr-down=name

Specifies which radius attributes contains rate information for upstream and downstream respectively.

burst-factor=n

Burst will be calculated as rate multyply burst-factor.

up-burst-factor=n

down-burst-factor=n

Specifies burst factor for upstream and downstream respectively.

latency=n

Specifies latency (in milliseconds) parameter of tbf qdisc.

mpu=n

Specifies mpu parameter of tbf qdisc and policer.

r2q=n

Specifies r2q parameter of root htb qdisc.

quantum=n

Specifies quantum parameter of htb classes.

moderate-quantum=1|0

If fixed quantum is not specified and this option is specified then shaper module will check for quantum value is valid (in range 1000-200000).

fwmark=n

Specifies the fwmark for traffic that won't be passed through shaper.

up-limiter=police|htb

Specifes upstream rate limiting method.

down-limiter=tbf|htb|clsact

Specifies downstream rate limiting method. clsact is a policer

leaf-qdisc=qdisc parameters

In case if tbf is used as down-limiter or htb is used as up-limiter or down-limiter specified leaf qdisc can be attached automatically. At present sfq and fq_codel qdiscs are implemented. Parameters are same as for tc:

sfq [ limit NUMBER ] [ perturn SECS ] [ quantum BYTES ]

fq_codel [ limit PACKETS ] [flows NUMBER ] [ target TIME ] [ interval TIME ] [quantum BYTES ] [ [no]ecn ]

rate-multiplier=n

Due to accel-ppp operates with rates in kilobit basis if you send rates in different basis then you can use this option to bring your values to kilobits.

rate-limit=download_speed/upload_speed

Specifies, should accel-ppp set default rate-limit for clients. Clients rate-limit will be overwritten by RADIUS filter attributes or chap-secrets rate-limit params.

## [cli]
Configuration of the command line interface.

verbose=n

If n = 1 then cli module will log IP address of each connection.

If n = 2 then cli module will also log passed commands.

tcp=host:port

Defines on which IP address and port the TCP module will listen for incoming connections. When host is empty, the TCP module listens on all local interfaces. It isn't loaded if this option isn't defined.

telnet=host:port

Defines on which IP address and port the Telnet module will listen for incoming connections. When host is empty, the Telnet module listens on all local interfaces. It isn't loaded if this option isn't defined.

password=passwd

Defines the password to be used by the TCP and Telnet modules for authenticating clients. No authentication is performed if this option isn't defined.

prompt=prompt

Defines the prompt string used by the Telnet module (defaults to accel-ppp).

history-file=filename

Defines the file used by the Telnet module for loading and storing its command history (defaults to /var/lib/accel-ppp/history).

sessions-columns=column_list

Defines the default set of columns to be displayed by the "show sessions" command (defaults to ifname,username,calling-sid,ip,rate-limit,type,comp,state,uptime).

Possible columns:

ifname - interface name

username - user name

ip - IP address

ip6 - IPv6 address

ip6-dp - IPv6 delegated prefix

type - connection type [pppoe|ipoe|pptp|l2tp|sstp]

state - state of session

uptime - uptime (human readable)

uptime-raw - uptime (in seconds)

calling-sid - calling station id

called-sid - called station id

sid - session id

comp - compression/encryption method

inbound-if - inbound interface

service-name - PPPoE service name

rx-bytes - received bytes (human readable)

tx-bytes - transmitted bytes (human readable)

rx-bytes-raw - received bytes

tx-bytes-raw - transmitted bytes

rx-pkts - received packets

tx-pkts - transmitted packets

netns - network namespaces

vrf - virtual routing and forwarding

Invalid column names are silently discarded.


acheck

package: acheck

title: acheck(5)

summary: Acheck configuration file

text:
# acheck(5)

## NAME
.acheck - Acheck configuration file

## DESCRIPTION
This is the configuration file for acheck. If it exists, it must be at the top of your home directory ($HOME). This file is optional unless you don't want to use default values.

Lines beginning with a number sign (`#') and empty lines will be ignored. Spaces at the beginning and the end of a line will also be ignored as well as tabulators. If you need spaces at the end or the beginning of a value you can use apostrophes (`"'). An option line starts with it's name followed by a value. An equal sign is optional. A comment starts with the number sign, there can be any number of spaces and/or tab stops in front of the #. Some possible examples:

```
 # this line is ignored
 option   value
 option = value                               # this is a comment
 option        "value ending with space   "
```

You have to escape number signs with a backslash (`\') to use it in a value.

Default values are provided into square brackets, they should be suitable for most installations.

## SPELLING
Define if you want to use ispell for checking spelling and how to use it.

check_spelling

use Aspell for spelling if set to `yes' [yes]

dictionary

Language dictionary to use with Aspell, use default if empty [empty]

word_letters

regular expression to define characters allowed to write a word, pattern matches according locale [\w]

$review_mode

set to `yes' if you want review comments to be added in the output file after parsed line, otherwise just fix error [no]

## COLORS
Set text colors for clear presentation.

The recognized colors (all of which should be fairly intuitive) are: clear, reset, dark, bold, underline, underscore, blink, reverse, concealed, black, red, green, yellow, blue, magenta, cyan, white, on_black, on_red, on_green, on_yellow, on_blue, on_magenta, on_cyan, and on_white. Case is not significant. Underline and underscore are equivalent, as are clear and reset, so use whichever is the most intuitive to you. The color alone sets the foreground color, and on_color sets the background color.

Note that not all colors are supported by all terminal types, and some terminals may not support any of these sequences. Dark, blink, and concealed in particular are frequently not implemented.

error_color

color used to highlight errors, this should highlight space characters [bold on_red]

fix_color

color used to highlight suggestions, this should highlight space characters [bold on_green]

error_head_color

color used to display the error line header [bold red]

error_color

color used to display the suggestion line header [bold green]

comment_color

color used for comments and hints [cyan]

## OTHERS
bak_ext

extension for backup files [bak]

comment

comment string for review [>> ]

debug

verbosity level [0]

Verbosity Levels:

0 quiet, normal

only warnings and errors

1 debug

names of subroutines

2 debug verbose

names and arguments of subroutines

3 .. 5 debug very verbose

output parsing and checking details

## SEE ALSO
acheck(1), acheck-rules(5)

## AUTHOR
Nicolas Bertolissio <bertol@debian.org>


acheck-rules

package: acheck-rules

title: acheck-rules(5)

summary: Rules set for acheck

text:
# acheck-rules(5)

## NAME
set.rules - Rules set for acheck

## DESCRIPTION
Rules set files contain rules to be check by acheck.

Lines beginning with a number sign (`#') and empty lines will be ignored. Spaces at the beginning and the end of a line will also be ignored as well as tabulators. If you need spaces at the end or the beginning of a value you can use apostrophes (`"'). A comment starts with the number sign, there can be any number of spaces and/or tab stops in front of the #. Long lines can be broken into multiple lines ending with a backslash (`\'). Some possible examples:

```
 # this line is ignored
 field    value
 field    value                               # this is a comment
 field         "value ending with space   "
 field    value\
          continuing on the next line
```

You have to escape number signs with a backslash to use it in a value and use apostrophes if a value ends with a backslash.

Rule sets are made of lists of rules. Theses lists can be repeated a number of times, until or while a condition happens.

A rule detects an error if the corresponding test succeeds and none of its validation tests does. Each rule can then produce some fixes, a warning or an error, and provide hints to help the operator to correct the error.

Parts of the text can be set as comments and so no rule and no spell check will be performed on them.

## SYNTAX RULES

### list
A list starts at a `list' statement, and stops at the first `end_list' or at the end of the file.

Mandatory fields:

type type

until, perform the list until the current line matches `test'

while, perform the lint while the current line matches `test'

loop, perform the list `test' times

test regex / number

A regex for `until' and `while' lists. The number of times the list must be performed for `loop', or `0' for infinite loop.

Optional fields:

name name

Use this to give the list a name.

spell yes / no

Set it to `yes' (default) or `no', if you want or don't want spelling to be checked in the lines matching this list. This value will be inherited by the nested lists.

Sub-rules:

list [name]

rule [name]

comment [name]

Followed by the name of the sub-rule or its definition for an anonymous sub-rule.

### rule
A rule starts at a `rule' statement, and stops at the first `end_rule' or at the beginning of a comment or a list.

Mandatory fields:

type type

fix, rule provides fixes and hints thought a menu

autofix, rule fixes the mistake with no interaction

warning, rule issues a warning

error, rule issues an error

nop, special rule that do nothing, no other field is required

regex regex

The regex to be match to found this error. Patterns can be captures and then used in the `fix' expression.

fix expr

Provides a correction for the rule, this field can be repeated to provides more than one choice. Only the first one will be used for `autofix' rules. `warning' and `error' do not provides fixes. The captured patterns can be used here with variables `$1', `$2', and so on.

hint text

Provides some explanations, this will be used as reviewer comments in review mode.

Optional fields:

name name

Use this to give the rule a name.

valid [name]

Provides a validation test, it can be named or anonymous. For anonymous validation, the test definition must follow. This field can be repeated more than once, if any of the validation test succeed, the rule does not apply.

### valid
A validation test starts at a `valid' statement, and stops at the first `end_valid' or at the beginning of a rule, a comment, a list or another validation test.

Mandatory field:

pre regex

in regex>

post regex

Try the regex before, in or after the match of the regex rule. At least one of these test must be provided. If all tests are successful, the rule won't apply.

Optional field:

name name

Use this to give the validation test a name.

### comment
A comment starts at a `comment' statement, and stops at the first `end_comment' or at the beginning of a rule, a comment or a list.

Comments are just skipped, no other rule and no spelling are performed on them.

Mandatory field:

skip regex

A regex matching the text of the comment. Do not use `start' and `stop' with this.

start regex

stop regex

Regexs defining the beginning and the end of the comment, all the text between will be considered as comment. Do not use `skip' with this.

Optional fields:

name name

Use this to give the comment a name.

start_offset

stop_offset

Defines where the comment really starts or end. Values are `s' for the place the match starts, `s+<n>' for n characters after the match starts, `e' for the place the match ends, or `e-<n>' for n characters before the match ends. Defaults are `s' for `start' matches and `e' for `stop' matches.

## SEE ALSO
acheck(1), acheck(5)

## AUTHOR
Nicolas Bertolissio <nico.bertol@free.fr>


acl

package: acl

title: acl(5)

summary: Access Control Lists

text:
# acl(5)

## NAME
acl — Access Control Lists

## DESCRIPTION
This manual page describes POSIX Access Control Lists, which are used to define more fine-grained discretionary access rights for files and directories.

## ACL TYPES
Every object can be thought of as having associated with it an ACL that governs the discretionary access to that object; this ACL is referred to as an access ACL. In addition, a directory may have an associated ACL that governs the initial access ACL for objects created within that directory; this ACL is referred to as a default ACL.

## ACL ENTRIES
An ACL consists of a set of ACL entries. An ACL entry specifies the access permissions on the associated object for an individual user or a group of users as a combination of read, write and search/execute permissions.

An ACL entry contains an entry tag type, an optional entry tag qualifier, and a set of permissions. We use the term qualifier to denote the entry tag qualifier of an ACL entry.

The qualifier denotes the identifier of a user or a group, for entries with tag types of ACL_USER or ACL_GROUP, respectively. Entries with tag types other than ACL_USER or ACL_GROUP have no defined qualifiers.

The following entry tag types are defined:

ACL_USER_OBJ

The ACL_USER_OBJ entry denotes access rights for the file owner.

ACL_USER

ACL_USER entries denote access rights for users identified by the entry's qualifier.

ACL_GROUP_OBJ

The ACL_GROUP_OBJ entry denotes access rights for the file group.

ACL_GROUP

ACL_GROUP entries denote access rights for groups identified by the entry's qualifier.

ACL_MASK

The ACL_MASK entry denotes the maximum access rights that can be granted by entries of type ACL_USER, ACL_GROUP_OBJ, or ACL_GROUP.

ACL_OTHER

The ACL_OTHER entry denotes access rights for processes that do not match any other entry in the ACL.

When an access check is performed, the ACL_USER_OBJ and ACL_USER entries are tested against the effective user ID. The effective group ID, as well as all supplementary group IDs are tested against the ACL_GROUP_OBJ and ACL_GROUP entries.

## VALID ACLs
A valid ACL contains exactly one entry with each of the ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER tag types. Entries with ACL_USER and ACL_GROUP tag types may appear zero or more times in an ACL. An ACL that contains entries of ACL_USER or ACL_GROUP tag types must contain exactly one entry of the ACL_MASK tag type. If an ACL contains no entries of ACL_USER or ACL_GROUP tag types, the ACL_MASK entry is optional.

All user ID qualifiers must be unique among all entries of ACL_USER tag type, and all group IDs must be unique among all entries of ACL_GROUP tag type.

The acl_get_file() function returns an ACL with zero ACL entries as the default ACL of a directory, if the directory is not associated with a default ACL. The acl_set_file() function also accepts an ACL with zero ACL entries as a valid default ACL for directories, denoting that the directory shall not be associated with a default ACL. This is equivalent to using the acl_delete_def_file() function.

## CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS
The permissions defined by ACLs are a superset of the permissions specified by the file permission bits.

There is a correspondence between the file owner, group, and other permissions and specific ACL entries: the owner permissions correspond to the permissions of the ACL_USER_OBJ entry. If the ACL has an ACL_MASK entry, the group permissions correspond to the permissions of the ACL_MASK entry. Otherwise, if the ACL has no ACL_MASK entry, the group permissions correspond to the permissions of the ACL_GROUP_OBJ entry. The other permissions correspond to the permissions of the ACL_OTHER entry.

The file owner, group, and other permissions always match the permissions of the corresponding ACL entry. Modification of the file permission bits results in the modification of the associated ACL entries, and modification of these ACL entries results in the modification of the file permission bits.

## OBJECT CREATION AND DEFAULT ACLs
The access ACL of a file object is initialized when the object is created with any of the creat(), mkdir(), mknod(), mkfifo(), or open() functions. If a default ACL is associated with a directory, the mode parameter to the functions creating file objects and the default ACL of the directory are used to determine the ACL of the new object:

- The new object inherits the default ACL of the containing directory as its access ACL.

- The access ACL entries corresponding to the file permission bits are modified so that they contain no permissions that are not contained in the permissions specified by the mode parameter.

If no default ACL is associated with a directory, the mode parameter to the functions creating file objects and the file creation mask (see umask(2)) are used to determine the ACL of the new object:

- The new object is assigned an access ACL containing entries of tag types ACL_USER_OBJ, ACL_GROUP_OBJ, and ACL_OTHER. The permissions of these entries are set to the permissions specified by the file creation mask.

- The access ACL entries corresponding to the file permission bits are modified so that they contain no permissions that are not contained in the permissions specified by the mode parameter.

## ACCESS CHECK ALGORITHM
A process may request read, write, or execute/search access to a file object protected by an ACL. The access check algorithm determines whether access to the object will be granted.

- If the effective user ID of the process matches the user ID of the file object owner, then if the ACL_USER_OBJ entry contains the requested permissions, access is granted, else access is denied.

- else if the effective user ID of the process matches the qualifier of any entry of type ACL_USER, then if the matching ACL_USER entry and the ACL_MASK entry contain the requested permissions, access is granted, else access is denied.

- else if the effective group ID or any of the supplementary group IDs of the process match the file group or the qualifier of any entry of type ACL_GROUP, then if the ACL contains an ACL_MASK entry, then if the ACL_MASK entry and any of the matching ACL_GROUP_OBJ or ACL_GROUP entries contain the requested permissions, access is granted, else access is denied.

else (note that there can be no ACL_GROUP entries without an ACL_MASK entry) if the ACL_GROUP_OBJ entry contains the requested permissions, access is granted, else access is denied.

- else if the ACL_OTHER entry contains the requested permissions, access is granted.

- else access is denied.

## ACL TEXT FORMS
A long and a short text form for representing ACLs is defined. In both forms, ACL entries are represented as three colon separated fields: an ACL entry tag type, an ACL entry qualifier, and the discretionary access permissions. The first field contains one of the following entry tag type keywords:

user

A user ACL entry specifies the access granted to either the file owner (entry tag type ACL_USER_OBJ) or a specified user (entry tag type ACL_USER).

group

A group ACL entry specifies the access granted to either the file group (entry tag type ACL_GROUP_OBJ) or a specified group (entry tag type ACL_GROUP).

mask

A mask ACL entry specifies the maximum access which can be granted by any ACL entry except the user entry for the file owner and the other entry (entry tag type ACL_MASK).

other

An other ACL entry specifies the access granted to any process that does not match any user or group ACL entries (entry tag type ACL_OTHER).

The second field contains the user or group identifier of the user or group associated with the ACL entry for entries of entry tag type ACL_USER or ACL_GROUP, and is empty for all other entries. A user identifier can be a user name or a user ID number in decimal form. A group identifier can be a group name or a group ID number in decimal form.

The third field contains the discretionary access permissions. The read, write and search/execute permissions are represented by the r, w, and x characters, in this order. Each of these characters is replaced by the - character to denote that a permission is absent in the ACL entry. When converting from the text form to the internal representation, permissions that are absent need not be specified.

White space is permitted at the beginning and end of each ACL entry, and immediately before and after a field separator (the colon character).

### LONG TEXT FORM
The long text form contains one ACL entry per line. In addition, a number sign (#) may start a comment that extends until the end of the line. If an ACL_USER, ACL_GROUP_OBJ or ACL_GROUP ACL entry contains permissions that are not also contained in the ACL_MASK entry, the entry is followed by a number sign, the string “effective:”, and the effective access permissions defined by that entry. This is an example of the long text form:

```
user::rw-
user:lisa:rw-         #effective:r--
group::r--
group:toolies:rw-     #effective:r--
mask::r--
other::r--
```

### SHORT TEXT FORM
The short text form is a sequence of ACL entries separated by commas, and is used for input. Comments are not supported. Entry tag type keywords may either appear in their full unabbreviated form, or in their single letter abbreviated form. The abbreviation for user is u, the abbreviation for group is g, the abbreviation for mask is m, and the abbreviation for other is o. The permissions may contain at most one each of the following characters in any order: r, w, x. These are examples of the short text form:

```
u::rw-,u:lisa:rw-,g::r--,g:toolies:rw-,m::r--,o::r--
g:toolies:rw,u:lisa:rw,u::wr,g::r,o::r,m::r
```

## RATIONALE
IEEE 1003.1e draft 17 defines Access Control Lists that include entries of tag type ACL_MASK, and defines a mapping between file permission bits that is not constant. The standard working group defined this relatively complex interface in order to ensure that applications that are compliant with IEEE 1003.1 (“POSIX.1”) will still function as expected on systems with ACLs. The IEEE 1003.1e draft 17 contains the rationale for choosing this interface in section B.23.

## CHANGES TO THE FILE UTILITIES
On a system that supports ACLs, the file utilities ls(1), cp(1), and mv(1) change their behavior in the following way:

- For files that have a default ACL or an access ACL that contains more than the three required ACL entries, the ls(1) utility in the long form produced by ls -l displays a plus sign (+) after the permission string.

- If the -p flag is specified, the cp(1) utility also preserves ACLs. If this is not possible, a warning is produced.

-

The mv(1) utility always preserves ACLs. If this is not possible, a warning is produced.

The effect of the chmod(1) utility, and of the chmod(2) system call, on the access ACL is described in CORRESPONDENCE BETWEEN ACL ENTRIES AND FILE PERMISSION BITS.

## STANDARDS
The IEEE 1003.1e draft 17 (“POSIX.1e”) document describes several security extensions to the IEEE 1003.1 standard. While the work on 1003.1e has been abandoned, many UNIX style systems implement parts of POSIX.1e draft 17, or of earlier drafts.

Linux Access Control Lists implement the full set of functions and utilities defined for Access Control Lists in POSIX.1e, and several extensions. The implementation is fully compliant with POSIX.1e draft 17; extensions are marked as such. The Access Control List manipulation functions are defined in the ACL library (libacl, -lacl). The POSIX compliant interfaces are declared in the <sys/acl.h> header. Linux-specific extensions to these functions are declared in the <acl/libacl.h> header.

## SEE ALSO
chmod(1), creat(2), getfacl(1), ls(1), mkdir(2), mkfifo(2), mknod(2), mount(8), open(2), setfacl(1), stat(2), umask(1)

### POSIX 1003.1e DRAFT 17
https://wt.tuxomania.net/publications/posix.1e/download.html

### POSIX 1003.1e FUNCTIONS BY CATEGORY
ACL storage management

acl_dup(3), acl_free(3), acl_init(3)

ACL entry manipulation

acl_copy_entry(3), acl_create_entry(3), acl_delete_entry(3), acl_get_entry(3), acl_valid(3) acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_delete_perm(3), acl_get_permset(3), acl_set_permset(3)

acl_get_qualifier(3), acl_get_tag_type(3), acl_set_qualifier(3), acl_set_tag_type(3)

ACL manipulation on an object

acl_delete_def_file(3), acl_get_fd(3), acl_get_file(3), acl_set_fd(3), acl_set_file(3)

ACL format translation

acl_copy_entry(3), acl_copy_ext(3), acl_from_text(3), acl_to_text(3), acl_size(3)

### POSIX 1003.1e FUNCTIONS BY AVAILABILITY
The first group of functions is supported on most systems with POSIX-like access control lists, while the second group is supported on fewer systems. For applications that will be ported the second group is best avoided.

acl_delete_def_file(3), acl_dup(3), acl_free(3), acl_from_text(3), acl_get_fd(3), acl_get_file(3), acl_init(3), acl_set_fd(3), acl_set_file(3), acl_to_text(3), acl_valid(3)

acl_add_perm(3), acl_calc_mask(3), acl_clear_perms(3), acl_copy_entry(3), acl_copy_ext(3), acl_copy_int(3), acl_create_entry(3), acl_delete_entry(3), acl_delete_perm(3), acl_get_entry(3), acl_get_permset(3), acl_get_qualifier(3), acl_get_tag_type(3), acl_set_permset(3), acl_set_qualifier(3), acl_set_tag_type(3), acl_size(3)

### LINUX EXTENSIONS
These non-portable extensions are available on Linux systems.

acl_check(3), acl_cmp(3), acl_entries(3), acl_equiv_mode(3), acl_error(3), acl_extended_fd(3), acl_extended_file(3), acl_extended_file_nofollow(3), acl_from_mode(3), acl_get_perm(3), acl_to_any_text(3)

## AUTHOR
Andreas Gruenbacher, <andreas.gruenbacher@gmail.com>


acmed.toml

package: acmed

title: acmed.toml(5)

summary: ACMEd configuration file

text:
# acmed.toml(5)

## NAME
acmed.toml — ACMEd configuration file

## DESCRIPTION
acmed.toml is the configuration file for acmed(8). It is written in the TOML format. The allowed elements are described below.

account

Array of table representing an account on one or several endpoint. contacts array

Array of tables describing describing the account holder's contact information. Each table must have one and only one key-value pair. Possible keys and their associated values are: mailto string

A mailto URI as defined by RFC 6068. This URI cannot contains neither “hfields” nor more than one “addr-spec” in the “to” component.

env table

Table of environment variables that will be accessible from hooks.

external_account table

Table containing the information required to bind the account to an external one. Possible fields and values are: identifier string

ASCII string identifying the key.

key string

Private key encoded in base64url without padding.

signature_algorithm string

Name of the signature algorithm used to sign the external account binding message sent to the endpoint as defined in RFC 7518. Possible values are:

- HS256 ⟨default⟩

- HS384

- HS512

hooks array

Names of hooks that will be called during operations on the account storage file. The hooks are guaranteed to be called sequentially in the declaration order.

key_type string

Name of the asymmetric cryptography algorithm used to generate the key pair. Possible values are:

- ed25519

- ed448

- ecdsa_p256 ⟨default⟩

- ecdsa_p384

- ecdsa_p521

- rsa2048

- rsa4096

name string

The name the account is registered under. Must be unique.

signature_algorithm string

Name of the signature algorithm used to sign the messages sent to the endpoint as defined in RFC 7518. The default value is derived from the key type. Possible values are:

- ES256

- ES384

- ES512

- RS256

certificate

Array of table representing a certificate that will be requested to a CA. Note that, by default, certificates are identified by the first identifier in the list of identifiers. That means that if you reorder the identifiers so that a different identifier is at the first position, a new certificate with a new name will be issued.

account string

Name of the account to use.

csr_digest string

Name of the certificate's signing request digest algorithm. Possible values are:

- sha256 ⟨default⟩

- sha384

- sha512

directory string

Path to the directory where certificates and their associated private keys are stored.

endpoint string

Name of the endpoint to use.

env table

Table of environment variables that will be accessible from hooks.

file_name_format string

Template used to build the file's name. The template syntax is MiniJinja. See the STANDARDS section for a link to the MiniJinja specifications. If not specified, the value defined in the endpoint element, and then the global element, is used. Default is “{{ name }}_{{ key_type }}.{{ file_type }}.{{ ext }}”. Possible variables are: ext string

File extension. See cert_file_ext and pk_file_ext.

file_type string

Contains “pk” for the private key file and “crt” for the certificate file.

key_type string

The certificate's private key type.

name string

The certificate's name.

hooks array

Names of hooks that will be called when requesting a new certificate. The hooks are guaranteed to be called sequentially in the declaration order.

identifiers array

Array of tables listing the identifiers that should be included in the certificate along with the challenge to use for each one. The dns and ip fields are mutually exclusive. challenge string

The name of the challenge to use to prove the identifier's ownership. Possible values are:

- dns-01

- http-01

- tls-alpn-01

dns string

The domain name.

env table

Table of environment variables that will be accessible from hooks.

ip string

The IP address.

key_type string

Name of the asymmetric cryptography algorithm used to generate the certificate's key pair. Possible values are:

- ed25519

- ed448

- ecdsa_p256

- ecdsa_p384

- ecdsa_p521

- rsa2048 ⟨default⟩

- rsa4096

kp_reuse boolean

Set whether or not the private key should be reused when renewing the certificate. Default is false.

name

Name of the certificate. Must be unique unless the key type is different. Will be used in logs and in the associated file's name. The ‘*’, ‘:’ and ‘/’ characters will be replaced by an underscore. Default is the first identifier.

random_early_renew string

Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the TIME PERIODS section. Default is the value defined in the associated endpoint.

renew_delay string

Period of time between the certificate renewal and its expiration date. The format is described in the TIME PERIODS section. Default is the value defined in the associated endpoint.

subject_attributes table

Table where the certificate's subject attributes are specified. Possible keys, with their RFC 4519 and X.500 equivalents, are: ACMEd key

RFC 4519

X.500

country_name

c

countryName

generation_qualifier

generationQualifier

given_name

givenName

initials

initials

locality_name

l

localityName

name

name

organization_name

o

organizationName

organizational_unit_name

ou

organizationalUnitName

pkcs9_email_address

postal_address

postalAddress

postal_code

postalCode

state_or_province_name

st

stateOrProvinceName

street

street

streetAddress

surname

sn

surname

title

title

endpoint

Array of table where each element defines a Certificate Authority (CA) which may be used to request certificates. file_name_format string

Template used to build the file's name. For detailed documentation, see the file_name_format directive located in the certificate element.

name string

The name the endpoint is registered under. Must be unique.

rate_limits array

Array containing the names of the HTTPS rate limits to apply.

random_early_renew string

Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the TIME PERIODS section. Default is the value defined in the global section.

renew_delay string

Period of time between the certificate renewal and its expiration date. The format is described in the TIME PERIODS section. Default is the value defined in the global section.

root_certificates array

Array containing the path to root certificates that should be added to the trust store.

tos_agreed boolean

Set whether or not the user agrees to the Terms Of Service (TOS).

url string

The endpoint's directory URL.

global

Table containing the global configuration options. accounts_directory string

Specify the directory where the accounts private and public keys are stored.

cert_file_group group_name|group_id string

Specify the group who will own newly-created certificates files. See chown(2) for more details.

cert_file_mode integer

Specify the permissions to use for newly-created certificates files. See chmod(2) for more details.

cert_file_user username|user_id string

Specify the user who will own newly-created certificates files. See chown(2) for more details.

cert_file_ext string

Specify the file extension of certificate files.

certificates_directory string

Specify the directory where the certificates and their associated private keys are stored.

env table

Table of environment variables that will be accessible from hooks.

file_name_format string

Template used to build the file's name. For detailed documentation, see the file_name_format directive located in the certificate element.

pk_file_group group_name|group_id string

Specify the group who will own newly-created private-key files. See chown(2) for more details.

pk_file_mode integer

Specify the permissions to use for newly-created private-key files. See chmod(2) for more details.

pk_file_user username|user_id string

Specify the user who will own newly-created private-key files. See chown(2) for more details.

pk_file_ext string

Specify the file extension of private-key files.

random_early_renew string

Period of time before the usual certificate renewal, in which the certificate will renew at a random time. This is useful for when you want to even out your certificate orders when you're dealing with very large numbers of certificates. The format is described in the TIME PERIODS section. By default, this is disabled, or rather, the time frame is set to 0.

renew_delay string

Period of time between the certificate renewal and its expiration date. The format is described in the TIME PERIODS section. Default is 30d.

root_certificates array

Array containing the path to root certificates that should be added to the trust store.

group

Array of table allowing to group several hooks as one. A group is considered as new hook. hooks array

Array containing the names of the hooks that are grouped. The hooks are guaranteed to be called sequentially in the declaration order.

name string

The name the group is registered under. This name is considered as a hook name. Must be unique.

hook

Array of table where each element defines a command that will be launched at a defined point. See section WRITING A HOOK for more details. allow_failure boolean

Defines if an error return value for this hook is allowed or not. If not allowed, a failure in this hook will fail the whole certificate request process. Default is false.

args array

Array of strings representing the command's arguments.

cmd string

The name of the command that will be launched.

name string

The name the hook is registered under. Must be unique.

stderr string

Path to the file where the command's standard error output if written.

stdin string

Path to the file that will be written into the command's standard intput. Mutually exclusive with stdin_str.

stdin_str string

String that will be written into the command's standard input. Mutually exclusive with stdin.

stdout string

Path to the file where the command's standard output if written.

type array

Array of strings. Possible types are:

- challenge-dns-01

- challenge-dns-01-clean

- challenge-http-01

- challenge-http-01-clean

- challenge-tls-alpn-01

- challenge-tls-alpn-01-clean

- file-post-create

- file-post-edit

- file-pre-create

- file-pre-edit

- post-operation

include

Array containing the path to configuration file to include. The path can be either relative or absolute. If relative, it is relative to the configuration file which included it. In case or overlapping global option definition, the one of the last included file will be used. For example, if a file A includes files B and C and all three defines the same global option, the final value will be the one defined in file C.

Unix style globing is supported.

rate-limit

Array of table where each element defines a HTTPS rate limit. name string

The name the rate limit is registered under. Must be unique.

number integer

Number of requests authorized withing the time period.

period string

Period of time during which a maximal number of requests is authorized. The format is described in the TIME PERIODS section.

## WRITING A HOOK
When requesting a certificate from a CA using ACME, there are three steps that are hard to automatize. The first one is solving challenges in order to prove the ownership of every identifier to be included: it requires to interact with the configuration of other services, hence depends on how the infrastructure works. The second one is restarting all the services that use a given certificate, for the same reason. The last one is archiving: although several default methods can be implemented, sometimes admins wants or are required to do it in a different way.

In order to allow full automation of the three above steps without imposing arbitrary restrictions or methods, acmed(8) uses hooks. Fundamentally, a hook is a command line template that will be called at a specific time of the process. Such an approach allows admins to use any executable script or program located on the machine to customize the process.

For a given certificate, hooks are guaranteed to be called sequentially in the declaration order. It is therefore possible to have a hook that depends on another one. Nevertheless, several certificates may be renewed at the same time. Hence, hooks shall not use globing or any other action that may disrupt hooks called by a different certificate.

A hook has a type that will influence both the moment it is called and the available template variables. It is possible to declare several types. In such a case, the hook will be invoked whenever one of its type request it. When called, the hook only have access to template variable for the current type. If a hook uses a template variable that does not exists for the current type it is invoked for, the variable is empty.

When writing a hook, the values of args, stdin, stdin_str, stdout and stderr are considered as template strings whereas cmd is not. The template syntax is MiniJinja. See the STANDARDS section for a link to the MiniJinja specifications.

The available types and the associated template variable are described below.

challenge-dns-01

Invoked when the ownership of an identifier must be proved using the dns-01 challenge. The available template variables are: challenge string

The name of the challenge type ⟨dns-01⟩. Mostly used in hooks with multiple types.

env array

Array containing all the environment variables.

identifier string

The identifier name whom ownership is currently being validated.

is_clean_hook bool

False

proof string

The content of the proof that must be written to a ‘TXT’ entry of the DNS zone for the ‘_acme-challenge’ subdomain.

challenge-dns-01-clean

Invoked once an identifier ownership has been proven using the dns-01 challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding challenge-dns-01 hook, excepted is_clean_hook which is set to true.

challenge-http-01

Invoked when the ownership of an identifier must be proved using the http-01 challenge. The available template variables are: challenge string

The name of the challenge type ⟨http-01⟩. Mostly used in hooks with multiple types.

env array

Array containing all the environment variables.

file_name string

Name of the file containing the proof. This is not a full path and does not include the ‘.well-known/acme-challenge/’ prefix.

identifier string

The identifier name whom ownership is currently being validated.

is_clean_hook bool

False

proof string

The content of the proof that must be written to file_name.

challenge-http-01-clean

Invoked once an identifier ownership has been proven using the http-01 challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding challenge-http-01 hook, excepted is_clean_hook which is set to true.

challenge-tls-alpn-01

Invoked when the ownership of an identifier must be proved using the tls-alpn-01 challenge. The available template variables are: challenge string

The name of the challenge type ⟨tls-alpn-01⟩. Mostly used in hooks with multiple types.

env array

Array containing all the environment variables.

identifier string

The identifier name whom ownership is currently being validated.

identifier_tls_alpn string

The identifier name whom ownership is currently being validated, in a form suitable for the TLS ALPN challenge.

is_clean_hook bool

False

proof string

Plain-text representation of the acmeIdentifier extension that should be used in the self-signed certificate presented when a TLS connection is initiated with the ALPN extension value. acmed(8) will not generate the certificate itself since it can be done using tacd(8).

raw_proof string

The SHA-256 digest of the key authorization, encoded using Base64 URL scheme without padding. This is intended for the use of ACMEd with a TLS-ALPN responder other than tacd(8).

challenge-tls-alpn-01-clean

Invoked once an identifier ownership has been proven using the tls-alpn-01 challenge. This hook is intended to remove the proof since it is no longer required. The template variables are strictly identical to those given in the corresponding challenge-tls-alpn-01 hook, excepted is_clean_hook which is set to true.

file-post-create

Invoked after a non-existent file created. The available template variables are the same as those available for the file-pre-create type.

file-post-edit

Invoked after an existent file modified. The available template variables are the same as those available for the file-pre-create type.

file-pre-create

Invoked before a non-existent file created. The available template variables are: env array

Array containing all the environment variables.

file_directory string

Name of the directory where the impacted file is located.

file_name string

Name of the impacted file.

file_path string

Full path to the impacted file.

file-pre-edit

Invoked before an existent file modified. The available template variables are the same as those available for the file-pre-create type.

post-operation

Invoked at the end of the certificate request process. The available template variables are: env array

Array containing all the environment variables.

identifiers string

Array containing the identifiers included in the requested certificate.

is_success boolean

True if the certificate request is successful.

key_type string

Name of the asymmetric cryptography algorithm used to generate the certificate's key pair.

status string

Human-readable status. If the certificate request failed, it contains the error description.

certificate_path string

Path to the file containing the certificate.

private_key_path string

Path to the file containing the private key.

## DEFAULT HOOKS
Because many people have the same needs, ACMEd comes with a set of hooks that should serve most situations. Hook names being unique, the following names and any other name starting by those is reserved and should not be used.

git

This hook uses git(1) to archive private keys, public keys and certificates. It is possible to customize the commit username and email by using respectively the GIT_USERNAME and GIT_EMAIL environment variables.

http-01-echo

This hook is designed to solve the http-01 challenge. For this purpose, it will write the proof into {{ env.HTTP_ROOT }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}. The web server must be configured so the file http://{{ identifier }}/.well-known/acme-challenge/{{ file_name }} can be accessed from the CA.

If HTTP_ROOT is not specified, it will be set to /var/www.

tls-alpn-01-tacd-tcp

This hook is designed to solve the tls-alpn-01 challenge using tacd(8). It requires pkill(1) to support the -F option. tacd(8) will listen on the host defined by the TACD_HOST environment variable (default is the identifier to be validated) and on the port defined by the TACD_PORT environment variable (default is 5001).

tacd(8) will store its pid into {{ TACD_PID_ROOT }}/tacd_{{ identifier }}.pid. If TACD_PID_ROOT is not specified, it will be set to /run.

tls-alpn-01-tacd-unix

This hook is designed to solve the tls-alpn-01 challenge using tacd(8). It requires pkill(1) to support the -F option. tacd(8) will listen on the unix socket {{ env.TACD_SOCK_ROOT }}/tacd_{{ identifier }}.sock. If TACD_SOCK_ROOT is not specified, it will be set to /run.

tacd(8) will store its pid into {{ TACD_PID_ROOT }}/tacd_{{ identifier }}.pid. If TACD_PID_ROOT is not specified, it will be set to /run.

## TIME PERIODS
ACMEd uses its own time period format, which is vaguely inspired by the ISO 8601 one. Periods are formatted as PM[PM...] where M is case sensitive character representing a length and P is an integer representing a multiplayer for the following length. The authorized length are:

- s: second

- m: minute

- h: hour

- d: day

- w: week

The PM couples can be specified multiple times and in any order. For example, “1d42s” and “40s20h4h2s” both represents a period of one day and forty-two seconds.

## TEMPLATE FILTERS
In addition the the filters provided by default by MiniJinja, ACMEd provides the following filters:

rev_labels

Reverts the labels of a domain name (eg: “mx1.example.org” becomes “org.example.mx1” ).

## FILES
/var/lib/acmed/accounts

Default accounts private and public keys directory.

/etc/acmed/acmed.toml

Default acmed(8) configuration file.

/var/lib/acmed/certs

Default certificates and associated private keys directory.

## EXAMPLES
The following example defines a typical endpoint, account and certificate for a domain, several subdomains and an IP address.

```
[[endpoint]]
name = "example name"
url = "https://acme.example.org/directory"
tos_agreed = true

[[account]]
name = "my test account"
contacts = [
  { mailto = "certs@exemple.net" }
]

[[certificate]]
endpoint = "example name"
account = "my test account"
identifiers = [
    { dns = "exemple.net", challenge = "http-01"},
    { dns = "1.exemple.net", challenge = "dns-01"},
    { dns = "2.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5010"},
    { dns = "3.exemple.net", challenge = "tls-alpn-01", env.TACD_PORT="5011"},
    { ip = "203.0.113.1", challenge = "http-01"},
]
hooks = ["git", "http-01-echo", "tls-alpn-01-tacd-tcp", "some-dns-01-hook"]
env.HTTP_ROOT = "/srv/http"
```

It is possible to use echo(1) to solve the http-01 challenge and rm(1) to clean it. mkdir(1) and chmod(1) are used to prevent issues related to file access.

```
[[hook]]
name = "http-01-echo-mkdir"
type = ["challenge-http-01"]
cmd = "mkdir"
args = [
    "-m", "0755",
    "-p", "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge"
]

[[hook]]
name = "http-01-echo-echo"
type = ["challenge-http-01"]
cmd = "echo"
args = ["{{ proof }}"]
stdout = "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"

[[hook]]
name = "http-01-echo-chmod"
type = ["challenge-http-01-clean"]
cmd = "chmod"
args = [
    "a+r",
    "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"
]

[[hook]]
name = "http-01-echo-clean"
type = ["challenge-http-01-clean"]
cmd = "rm"
args = [
    "-f",
    "{{ env.HTTP_ROOT | default('/var/www') }}/{{ identifier }}/.well-known/acme-challenge/{{ file_name }}"
]
```

The hooks from the previous example can be grouped in order to reduce the number of hooks to define in the certificate.

```
[[group]]
name = "http-01-echo-var-www"
hooks = [
    "http-01-echo-mkdir",
    "http-01-echo-echo",
    "http-01-echo-chmod",
    "http-01-echo-clean"
]

[[certificate]]
# Some fields omitted
hooks = ["http-01-echo"]
env.HTTP_ROOT = "/srv/http"
```

It is also possible to use sendmail(8) in a hook in order to notify someone when the certificate request process is done.

```
[[hook]]
name = "email-report"
type = ["post-operation"]
cmd = "sendmail"
args = [
    "-f", "noreply.certs@example.net",
    "contact@example.net"
]
stdin_str = """Subject: Certificate renewal {{ 'succeeded' if is_success else 'failed' }} for {{ identifiers.0 }}

The following certificate has {{ '' if is_success else '*not* ' }}been renewed.
identifiers: {% for ident in identifiers %}{% if not loop.first %}, {% endif %}{{ ident }}{% endfor %}
key type: {{ key_type }}
status: {{ status }}"""
```

## SEE ALSO
acmed(8), tacd(8)

## STANDARDS

- Tom Preston-Werner, TOML v0.5.0, https://toml.io/en/v0.5.0, July 2018.

- Armin Ronacher, MiniJinja, https://docs.rs/minijinja/latest/minijinja/syntax/index.html.

- M. Jones, JSON Web Algorithms (JWA), RFC 7518, May 2015.

## AUTHORS
Rodolphe Bréard ⟨rodolphe@breard.tf⟩