diff options
Diffstat (limited to 'doc/1.6')
| -rw-r--r-- | doc/1.6/radsecproxy-hash.html | 117 | ||||
| -rw-r--r-- | doc/1.6/radsecproxy.conf.html | 886 | ||||
| -rw-r--r-- | doc/1.6/radsecproxy.html | 251 |
3 files changed, 1254 insertions, 0 deletions
diff --git a/doc/1.6/radsecproxy-hash.html b/doc/1.6/radsecproxy-hash.html new file mode 100644 index 0000000..9bf298b --- /dev/null +++ b/doc/1.6/radsecproxy-hash.html @@ -0,0 +1,117 @@ +<!-- Creator : groff version 1.22.2 --> +<!-- CreationDate: Thu Sep 17 10:29:24 2015 --> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" +"http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta name="generator" content="groff -Thtml, see www.gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<meta name="Content-Style" content="text/css"> +<style type="text/css"> + p { margin-top: 0; margin-bottom: 0; vertical-align: top } + pre { margin-top: 0; margin-bottom: 0; vertical-align: top } + table { margin-top: 0; margin-bottom: 0; vertical-align: top } + h1 { text-align: center } +</style> +<title>radsecproxy-hash</title> + +</head> +<body> + +<h1 align="center">radsecproxy-hash</h1> + +<a href="#NAME">NAME</a><br> +<a href="#SYNOPSIS">SYNOPSIS</a><br> +<a href="#DESCRIPTION">DESCRIPTION</a><br> +<a href="#OPTIONS">OPTIONS</a><br> +<a href="#SEE ALSO">SEE ALSO</a><br> + +<hr> + + +<h2>NAME +<a name="NAME"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy-hash +- print digests of Ethernet MAC addresses</p> + +<h2>SYNOPSIS +<a name="SYNOPSIS"></a> +</h2> + + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="61%"> + + +<p style="margin-top: 1em">radsecproxy-hash [−h] +[−k key] [−t type]</p></td> +<td width="28%"> +</td></tr> +</table> + +<h2>DESCRIPTION +<a name="DESCRIPTION"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">Print the hash +or hmac of Ethernet MAC addresses read from standard +input.</p> + +<h2>OPTIONS +<a name="OPTIONS"></a> +</h2> + + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="9%"> + + +<p style="margin-top: 1em"><b>−h</b></p></td> +<td width="2%"></td> +<td width="43%"> + + +<p style="margin-top: 1em"><i>display help and exit</i></p></td> +<td width="35%"> +</td></tr> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="9%"> + + +<p><b>−k key</b></p></td> +<td width="2%"></td> +<td width="43%"> + + +<p><i>use KEY for HMAC calculation</i></p></td> +<td width="35%"> +</td></tr> +</table> + +<p style="margin-left:11%;"><b>−t type</b></p> + +<p style="margin-left:22%;"><i>print digest of type TYPE +[hash|hmac]</i></p> + +<h2>SEE ALSO +<a name="SEE ALSO"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy.conf(5)</p> +<hr> +</body> +</html> diff --git a/doc/1.6/radsecproxy.conf.html b/doc/1.6/radsecproxy.conf.html new file mode 100644 index 0000000..1780a13 --- /dev/null +++ b/doc/1.6/radsecproxy.conf.html @@ -0,0 +1,886 @@ +<!-- Creator : groff version 1.22.2 --> +<!-- CreationDate: Thu Sep 17 10:29:24 2015 --> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" +"http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta name="generator" content="groff -Thtml, see www.gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<meta name="Content-Style" content="text/css"> +<style type="text/css"> + p { margin-top: 0; margin-bottom: 0; vertical-align: top } + pre { margin-top: 0; margin-bottom: 0; vertical-align: top } + table { margin-top: 0; margin-bottom: 0; vertical-align: top } + h1 { text-align: center } +</style> +<title>radsecproxy.conf</title> + +</head> +<body> + +<h1 align="center">radsecproxy.conf</h1> + +<a href="#NAME">NAME</a><br> +<a href="#DESCRIPTION">DESCRIPTION</a><br> +<a href="#CONFIGURATION SYNTAX">CONFIGURATION SYNTAX</a><br> +<a href="#BASIC OPTIONS">BASIC OPTIONS</a><br> +<a href="#BLOCKS">BLOCKS</a><br> +<a href="#CLIENT BLOCK">CLIENT BLOCK</a><br> +<a href="#SERVER BLOCK">SERVER BLOCK</a><br> +<a href="#REALM BLOCK">REALM BLOCK</a><br> +<a href="#TLS BLOCK">TLS BLOCK</a><br> +<a href="#REWRITE BLOCK">REWRITE BLOCK</a><br> +<a href="#SEE ALSO">SEE ALSO</a><br> + +<hr> + + +<h2>NAME +<a name="NAME"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy.conf +− Radsec proxy configuration file</p> + +<h2>DESCRIPTION +<a name="DESCRIPTION"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">When the proxy +server starts, it will first check the command line +arguments, and then read the configuration file. Normally +radsecproxy will read the configuration file +<i>/usr/local/etc/radsecproxy.conf</i>. The command line +<b>−c</b> option can be used to instead read an +alternate file (see <b>radsecproxy</b>(1) for details).</p> + +<p style="margin-left:11%; margin-top: 1em">If the +configuration file can not be found, the proxy will exit +with an error message. Note that there is also an include +facility so that any configuration file may include other +configuration files. The proxy will also exit on +configuration errors.</p> + +<h2>CONFIGURATION SYNTAX +<a name="CONFIGURATION SYNTAX"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">When the +configuration file is processed, whitespace (spaces and +tabs) are generally ignored. For each line, leading and +trailing whitespace are ignored. A line is ignored if it is +empty, only consists of whitespace, or if the first +non-whitespace character is a #. The configuration is +generally case insensitive, but in some cases the option +values (see below) are not.</p> + +<p style="margin-left:11%; margin-top: 1em">There are two +types of configuration structures than can be used. The +first and simplest are lines on the format <i>option +value</i>. That is, an option name, see below for a list of +valid options, followed by whitespace (at least one space or +tab character), followed by a value. Note that if the value +contains whitespace, then it must be quoted using +"" or ’’. Any whitespace in front of +the option or after the value will be ignored.</p> + +<p style="margin-left:11%; margin-top: 1em">The other type +of structure is a block. A block spans at least two lines, +and has the format:</p> + +<p style="margin-left:22%; margin-top: 1em">blocktype name +{ <br> +option value <br> +option value <br> +... <br> +}</p> + +<p style="margin-left:11%; margin-top: 1em">That is, some +blocktype, see below for a list of the different block +types, and then enclosed in braces you have zero or more +lines that each have the previously described <i>option +value</i> format. Different block types have different rules +for which options can be specified, they are listed below. +The rules regarding white space, comments and quotes are as +above. Hence you may do things like:</p> + +<p style="margin-left:22%; margin-top: 1em">blocktype name +{ <br> +# option value <br> +option "value with space" <br> +... <br> +}</p> + +<p style="margin-left:11%; margin-top: 1em">Option value +characters can also be written in hex. This is done by +writing the character % followed by two hexadecimal digits. +If a % is used without two following hexadecimal digits, the +% and the following characters are used as written. If you +want to write a % and not use this decoding, you may of +course write % in hex; i.e., %25.</p> + +<p style="margin-left:11%; margin-top: 1em">There is one +special option that can be used both as a basic option and +inside all blocks. That is the option Include where the +value specifies files to be included. The value can be a +single file, or it can use normal shell globbing to specify +multiple files, e.g.:</p> + +<p style="margin-left:22%;">include +/usr/local/etc/radsecproxy.conf.d/*.conf</p> + +<p style="margin-left:11%; margin-top: 1em">The files are +sorted alphabetically. Included files are read in the order +they are specified, when reaching the end of a file, the +next file is read. When reaching the end of the last +included file, the proxy returns to read the next line +following the Include option. Included files may again +include other files.</p> + +<h2>BASIC OPTIONS +<a name="BASIC OPTIONS"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The following +basic options may be specified in the configuration file. +Note that blocktypes and options inside blocks are discussed +later. Note that none of these options are required, and +indeed in many cases they are not needed. Note that you +should specify each at most once. The behaviour with +multiple occurences is undefined. <br> +PidFile</p> + +<p style="margin-left:22%;">The PidFile option specifies +the name of a file to which the process id (PID) will be +written. This is overridden by the <b>−i</b> command +line option. There is no default value for the PidFile +option.</p> + +<p style="margin-left:11%;">LogLevel</p> + +<p style="margin-left:22%;">This option specifies the debug +level. It must be set to 1, 2, 3, 4 or 5, where 1 logs only +serious errors, and 5 logs everything. The default is 2 +which logs errors, warnings and a few informational +messages. Note that the command line option <b>−d</b> +overrides this.</p> + +<p style="margin-left:11%;">LogDestination</p> + +<p style="margin-left:22%;">This specifies where the log +messages should go. By default the messages go to syslog +with facility LOG_DAEMON. Using this option you can specify +another syslog facility, or you may specify that logging +should be to a particular file, not using syslog. The value +must be either a file or syslog URL. The file URL is the +standard one, specifying a local file that should be used. +For syslog, you must use the syntax: +x−syslog:///FACILITY where FACILITY must be one of +LOG_DAEMON, LOG_MAIL, LOG_USER, LOG_LOCAL0, LOG_LOCAL1, +LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4, LOG_LOCAL5, LOG_LOCAL6 +or LOG_LOCAL7. You may omit the facility from the URL to +specify logging to the default facility, but this is not +very useful since this is the default log destination. Note +that this option is ignored if <b>−f</b> is specified +on the command line.</p> + +<p style="margin-left:11%;">FTicksReporting</p> + +<p style="margin-left:22%;">The FTicksReporting option is +used to enable F-Ticks logging and can be set to None, Basic +or Full. Its default value is None. If FTicksReporting is +set to anything other than None, note that the default value +for FTicksMAC is VendorKeyHashed which needs FTicksKey to be +set.</p> + +<p style="margin-left:22%; margin-top: 1em">See +radsecproxy.conf−example for details. Note that +radsecproxy has to be configured with F-Ticks support +(−−enable−fticks) for this option to have +any effect.</p> + +<p style="margin-left:11%;">FTicksMAC</p> + +<p style="margin-left:22%;">The FTicksMAC option can be +used to control if and how Calling-Station-Id (the users +Ethernet MAC address) is being logged. It can be set to one +of Static, Original, VendorHashed, VendorKeyHashed, +FullyHashed or FullyKeyHashed.</p> + +<p style="margin-left:22%; margin-top: 1em">The default +value for FTicksMAC is VendorKeyHashed. This means that +FTicksKey has to be set.</p> + +<p style="margin-left:22%; margin-top: 1em">Before chosing +any of Original, FullyHashed or VendorHashed, consider the +implications for user privacy when MAC addresses are +collected. How will the logs be stored, transferred and +accessed?</p> + +<p style="margin-left:22%; margin-top: 1em">See +radsecproxy.conf−example for details. Note that +radsecproxy has to be configured with F-Ticks support +(−−enable−fticks) for this option to have +any effect.</p> + +<p style="margin-left:11%;">FTicksKey</p> + +<p style="margin-left:22%;">The FTicksKey option is used to +specify the key to use when producing HMAC’s as an +effect of specifying VendorKeyHashed or FullyKeyHashed for +the FTicksMAC option.</p> + +<p style="margin-left:22%; margin-top: 1em">Note that +radsecproxy has to be configured with F-Ticks support +(−−enable−fticks) for this option to have +any effect.</p> + +<p style="margin-left:11%;">FTicksSyslogFacility</p> + +<p style="margin-left:22%;">The FTicksSyslogFacility option +is used to specify a dedicated syslog facility for F-Ticks +messages. This allows for easier filtering of F-Ticks +messages. If no FTicksSyslogFacility option is given, +F-Ticks messages are written to what the LogDestination +option specifies.</p> + +<p style="margin-left:22%; margin-top: 1em">F-Ticks +messages are always logged using the log level LOG_DEBUG. +Note that specifying a file in FTicksSyslogFacility (using +the file:/// prefix) is not supported.</p> + +<p style="margin-left:11%;">ListenUDP</p> + +<p style="margin-left:22%;">Normally the proxy will listen +to the standard RADIUS UDP port 1812 if configured to handle +UDP clients. On most systems it will do this for all of the +system’s IP addresses (both IPv4 and IPv6). On some +systems however, it may respond to only IPv4 or only IPv6. +To specify an alternate port you may use a value on the form +*:port where port is any valid port number. If you also want +to specify a specific address you can do e.g. +192.168.1.1:1812 or [2001:db8::1]:1812. The port may be +omitted if you want the default one (like in these +examples). These examples are equivalent to 192.168.1.1 and +2001:db8::1. Note that you must use brackets around the IPv6 +address. This option may be specified multiple times to +listen to multiple addresses and/or ports.</p> + +<p style="margin-left:11%;">ListenTCP</p> + +<p style="margin-left:22%;">This option is similar to the +ListenUDP option, except that it is used for receiving +connections from TCP clients. The default port number is +1812.</p> + +<p style="margin-left:11%;">ListenTLS</p> + +<p style="margin-left:22%;">This is similar to the +ListenUDP option, except that it is used for receiving +connections from TLS clients. The default port number is +2083. Note that this option was previously called +ListenTCP.</p> + +<p style="margin-left:11%;">ListenDTLS</p> + +<p style="margin-left:22%;">This is similar to the +ListenUDP option, except that it is used for receiving +connections from DTLS clients. The default port number is +2083.</p> + +<p style="margin-left:11%;">SourceUDP</p> + +<p style="margin-left:22%;">This can be used to specify +source address and/or source port that the proxy will use +for sending UDP client messages (e.g. Access Request).</p> + +<p style="margin-left:11%;">SourceTCP</p> + +<p style="margin-left:22%;">This can be used to specify +source address and/or source port that the proxy will use +for TCP connections.</p> + +<p style="margin-left:11%;">SourceTLS</p> + +<p style="margin-left:22%;">This can be used to specify +source address and/or source port that the proxy will use +for TLS connections.</p> + +<p style="margin-left:11%;">SourceDTLS</p> + +<p style="margin-left:22%;">This can be used to specify +source address and/or source port that the proxy will use +for DTLS connections.</p> + +<p style="margin-left:11%;">TTLAttribute</p> + +<p style="margin-left:22%;">This can be used to change the +default TTL attribute. Only change this if you know what you +are doing. The syntax is either a numerical value denoting +the TTL attribute, or two numerical values separated by +column specifying a vendor attribute, i.e. +vendorid:attribute.</p> + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="9%"> + + +<p>AddTTL</p></td> +<td width="2%"></td> +<td width="78%"> + + +<p>If a TTL attribute is present, the proxy will decrement +the value and discard the message if zero. Normally the +proxy does nothing if no TTL attribute is present. If you +use the AddTTL option with a value 1-255, the proxy will +when forwarding a message with no TTL attribute, add one +with the specified value. Note that this option can also be +specified for a client/server. It will then override this +setting when forwarding a message to that client/server.</p></td></tr> +</table> + +<p style="margin-left:11%;">LoopPrevention</p> + +<p style="margin-left:22%;">This can be set to on or off +with off being the default. When this is enabled, a request +will never be sent to a server named the same as the client +it was received from. I.e., the names of the client block +and the server block are compared. Note that this only gives +limited protection against loops. It can be used as a basic +option and inside server blocks where it overrides the basic +setting.</p> + +<p style="margin-left:11%;">IPv4Only and IPv6Only</p> + +<p style="margin-left:22%;">These can be set to on or off +with off being the default. At most one of IPv4Only and +IPv6Only can be enabled. Enabling IPv4Only or IPv6Only makes +radsecproxy resolve DNS names to the corresponding address +family only, and not the other. This is done for both +clients and servers. Note that this can be overridden in +client and server blocks, see below.</p> + +<p style="margin-left:11%;">Include</p> + +<p style="margin-left:22%;">This is not a normal +configuration option; it can be specified multiple times. It +can both be used as a basic option and inside blocks. For +the full description, see the configuration syntax section +above.</p> + +<h2>BLOCKS +<a name="BLOCKS"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">There are five +types of blocks, they are client, server, realm, tls and +rewrite. At least one instance of each of client and realm +is required. This is necessary for the proxy to do anything +useful, and it will exit if not. The tls block is required +if at least one TLS/DTLS client or server is configured. +Note that there can be multiple blocks for each type. For +each type, the block names should be unique. The behaviour +with multiple occurences of the same name for the same block +type is undefined. Also note that some block option values +may reference a block by name, in which case the block name +must be previously defined. Hence the order of the blocks +may be significant.</p> + +<h2>CLIENT BLOCK +<a name="CLIENT BLOCK"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The client +block is used to configure a client. That is, tell the proxy +about a client, and what parameters should be used for that +client. The name of the client block must (with one +exception, see below) be either the IP address (IPv4 or +IPv6) of the client, an IP prefix (IPv4 or IPv6) on the form +IpAddress/PrefixLength, or a domain name (FQDN). The way an +FQDN is resolved into an IP address may be influenced by the +use of the IPv4Only and IPv6Only options. Note that literal +IPv6 addresses must be enclosed in brackets.</p> + +<p style="margin-left:11%; margin-top: 1em">If a domain +name is specified, then this will be resolved immediately to +all the addresses associated with the name, and the proxy +will not care about any possible DNS changes that might +occur later. Hence there is no dependency on DNS after +startup.</p> + +<p style="margin-left:11%; margin-top: 1em">When some +client later sends a request to the proxy, the proxy will +look at the IP address the request comes from, and then go +through all the addresses of each of the configured clients +(in the order they are defined), to determine which (if any) +of the clients this is.</p> + +<p style="margin-left:11%; margin-top: 1em">In the case of +TLS/DTLS, the name of the client must match the FQDN or IP +address in the client certificate. Note that this is not +required when the client name is an IP prefix.</p> + +<p style="margin-left:11%; margin-top: 1em">Alternatively +one may use the host option inside a client block. In that +case, the value of the host option is used as above, while +the name of the block is only used as a descriptive name for +the administrator. The host option may be used multiple +times, and can be a mix of addresses, FQDNs and +prefixes.</p> + +<p style="margin-left:11%; margin-top: 1em">The allowed +options in a client block are host, IPv4Only, IPv6Only, +type, secret, tls, certificateNameCheck, +matchCertificateAttribute, duplicateInterval, AddTTL, +fticksVISCOUNTRY, fticksVISINST, rewrite, rewriteIn, +rewriteOut, and rewriteAttribute. We already discussed the +host option. To specify how radsecproxy should resolve a +host given as a DNS name, the IPv4Only or the IPv6Only can +be set to on. At most one of these options can be enabled. +Enabling IPv4Only or IPv6Only here overrides any basic +settings set at the top level. The value of type must be one +of udp, tcp, tls or dtls. The value of secret is the shared +RADIUS key used with this client. If the secret contains +whitespace, the value must be quoted. This option is +optional for TLS/DTLS and if omitted will default to +"radsec". (Note that using a secret other than +"radsec" for TLS is a violation of the standard +(RFC 6614) and that the proposed standard for DTLS +stipulates that the secret must be +"radius/dtls".)</p> + +<p style="margin-left:11%; margin-top: 1em">For a TLS/DTLS +client you may also specify the tls option. The option value +must be the name of a previously defined TLS block. If this +option is not specified, the TLS block with the name +defaultClient will be used if defined. If not defined, it +will try to use the TLS block named default. If the +specified TLS block name does not exist, or the option is +not specified and none of the defaults exist, the proxy will +exit with an error. NOTE: All versions of radsecproxy up to +and including 1.6 erroneously verify client certificate +chains using the CA in the very first matching client block +regardless of which block is used for the final decision. +This was changed in version 1.6.1 so that a client block +with a different tls option than the first matching client +block is no longer considered for verification of +clients.</p> + +<p style="margin-left:11%; margin-top: 1em">For a TLS/DTLS +client, the option certificateNameCheck can be set to off, +to disable the default behaviour of matching CN or +SubjectAltName against the specified hostname or IP +address.</p> + +<p style="margin-left:11%; margin-top: 1em">Additional +validation of certificate attributes can be done by use of +the matchCertificateAttribute option. Currently one can only +do some matching of CN and SubjectAltName. For regexp +matching on CN, one can use the value CN:/regexp/. For +SubjectAltName one can only do regexp matching of the URI, +this is specified as SubjectAltName:URI:/regexp/. Note that +currently this option can only be specified once in a client +block.</p> + +<p style="margin-left:11%; margin-top: 1em">The +duplicateInterval option can be used to specify for how many +seconds duplicate checking should be done. If a proxy +receives a new request within a few seconds of a previous +one, it may be treated the same if from the same client, +with the same authenticator etc. The proxy will then ignore +the new request (if it is still processing the previous +one), or returned a copy of the previous reply.</p> + +<p style="margin-left:11%; margin-top: 1em">The AddTTL +option is similar to the AddTTL option used in the basic +config. See that for details. Any value configured here +overrides the basic one when sending messages to this +client.</p> + +<p style="margin-left:11%; margin-top: 1em">The +fticksVISCOUNTRY option configures clients eligible to +F-Ticks logging as defined by the FTicksReporting basic +option.</p> + +<p style="margin-left:11%; margin-top: 1em">The +fticksVISINST option overwrites the default VISINST value +taken from the client block name.</p> + +<p style="margin-left:11%; margin-top: 1em">The rewrite +option is deprecated. Use rewriteIn instead.</p> + +<p style="margin-left:11%; margin-top: 1em">The rewriteIn +option can be used to refer to a rewrite block that +specifies certain rewrite operations that should be +performed on incoming messages from the client. The +rewriting is done before other processing. For details, see +the rewrite block text below. Similarly to tls discussed +above, if this option is not used, there is a fallback to +using the rewrite block named defaultClient if it exists; +and if not, a fallback to a block named default.</p> + +<p style="margin-left:11%; margin-top: 1em">The rewriteOut +option is used in the same way as rewriteIn, except that it +specifies rewrite operations that should be performed on +outgoing messages to the client. The rewriting is done after +other processing. Also, there is no rewrite fallback if this +option is not used.</p> + +<p style="margin-left:11%; margin-top: 1em">The +rewriteAttribute option currently makes it possible to +specify that the User-Name attribute in a client request +shall be rewritten in the request sent by the proxy. The +User-Name attribute is written back to the original value if +a matching response is later sent back to the client. The +value must be on the form +User-Name:/regexpmatch/replacement/. Example usage:</p> + +<p style="margin-left:22%;">rewriteAttribute +User-Name:/^(.*)@local$/\1@example.com/</p> + +<h2>SERVER BLOCK +<a name="SERVER BLOCK"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The server +block is used to configure a server. That is, tell the proxy +about a server, and what parameters should be used when +communicating with that server. The name of the server block +must (with one exception, see below) be either the IP +address (IPv4 or IPv6) of the server, or a domain name +(FQDN). If a domain name is specified, then this will be +resolved immediately to all the addresses associated with +the name, and the proxy will not care about any possible DNS +changes that might occur later. Hence there is no dependency +on DNS after startup. If the domain name resolves to +multiple addresses, then for UDP/DTLS the first address is +used. For TCP/TLS, the proxy will loop through the addresses +until it can connect to one of them. The way an FQDN is +resolved into an IP address may be influenced by the use of +the IPv4Only and IPv6Only options. In the case of TLS/DTLS, +the name of the server must match the FQDN or IP address in +the server certificate.</p> + +<p style="margin-left:11%; margin-top: 1em">Alternatively +one may use the host option inside a server block. In that +case, the value of the host option is used as above, while +the name of the block is only used as a descriptive name for +the administrator. Note that multiple host options may be +used. This will then be treated as multiple names/addresses +for the same server. When initiating a TCP/TLS connection, +all addresses of all names may be attempted, but there is no +failover between the different host values. For failover one +must use separate server blocks.</p> + +<p style="margin-left:11%; margin-top: 1em">Note that the +name of the block, or values of host options may include a +port number (separated with a column). This port number will +then override the default port or a port option in the +server block. Also note that literal IPv6 addresses must be +enclosed in brackets.</p> + +<p style="margin-left:11%; margin-top: 1em">The allowed +options in a server block are host, port, IPv4Only, +IPv6Only, type, secret, tls, certificateNameCheck, +matchCertificateAttribute, AddTTL, rewrite, rewriteIn, +rewriteOut, statusServer, retryCount, dynamicLookupCommand +and retryInterval and LoopPrevention.</p> + +<p style="margin-left:11%; margin-top: 1em">We already +discussed the host option. To specify how radsecproxy should +resolve a host given as a DNS name, the IPv4Only or the +IPv6Only can be set to on. At most one of these options can +be enabled. Enabling IPv4Only or IPv6Only here overrides any +basic settings set at the top level. The port option allows +you to specify which port number the server uses. The usage +of type, secret, tls, certificateNameCheck, +matchCertificateAttribute, AddTTL, rewrite, rewriteIn and +rewriteOut are just as specified for the client block above, +except that defaultServer (and not defaultClient) is the +fallback for the tls, rewrite and rewriteIn options.</p> + +<p style="margin-left:11%; margin-top: 1em">statusServer +can be specified to enable the use of status-server messages +for this server. The value must be either on or off. The +default when not specified, is off. If statusserver is +enabled, the proxy will during idle periods send regular +status-server messages to the server to verify that it is +alive. This should only be enabled if the server supports +it.</p> + +<p style="margin-left:11%; margin-top: 1em">The options +retryCount and retryInterval can be used to specify how many +times the proxy should retry sending a request and how long +it should wait between each retry. The defaults are 2 +retries and an interval of 5s.</p> + +<p style="margin-left:11%; margin-top: 1em">The option +dynamicLookupCommand can be used to specify a command that +should be executed to dynamically configure a server. The +executable file should be given with full path and will be +invoked with the name of the realm as its first and only +argument. It should either print a valid server option on +stdout and exit with a code of 0 or print nothing and exit +with a non-zero exit code. An example of a shell script +resolving the DNS NAPTR records for the realm and then the +SRV records for each NAPTR matching +’x-eduroam:radius.tls’ is provided in +tools/naptr−eduroam.sh. This option was added in +radsecproxy-1.3 but tends to crash radsecproxy versions +earlier than 1.6.</p> + +<p style="margin-left:11%; margin-top: 1em">Using the +LoopPrevention option here overrides any basic setting of +this option. See section BASIC OPTIONS for details on this +option.</p> + +<h2>REALM BLOCK +<a name="REALM BLOCK"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">When the proxy +receives an Access-Request it needs to figure out to which +server it should be forwarded. This is done by looking at +the Username attribute in the request, and matching that +against the names of the defined realm blocks. The proxy +will match against the blocks in the order they are +specified, using the first match if any. If no realm +matches, the proxy will simply ignore the request. Each +realm block specifies what the server should do when a match +is found. A realm block may contain none, one or multiple +server options, and similarly accountingServer options. +There are also replyMessage and accountingResponse options. +We will discuss these later.</p> + +<p style="margin-left:11%; margin-top: 1em"><b>REALM BLOCK +NAMES AND MATCHING</b> <br> +In the general case the proxy will look for a @ in the +username attribute, and try to do an exact case insensitive +match between what comes after the @ and the name of the +realm block. So if you get a request with the attribute +value anonymous@example.com, the proxy will go through the +realm names in the order they are specified, looking for a +realm block named example.com.</p> + +<p style="margin-left:11%; margin-top: 1em">There are two +exceptions to this, one is the realm name * which means +match everything. Hence if you have a realm block named *, +then it will always match. This should then be the last +realm block defined, since any blocks after this would never +be checked. This is useful for having a default.</p> + +<p style="margin-left:11%; margin-top: 1em">The other +exception is regular expression matching. If the realm name +starts with a /, the name is treated as an regular +expression. A case insensitive regexp match will then be +done using this regexp on the value of the entire Username +attribute. Optionally you may also have a trailing / after +the regexp. So as an example, if you want to use regexp +matching the domain example.com you could have a realm block +named /@example\\.com$. Optinally this can also be written +/@example\\.com$/. If you want to match all domains under +the .com top domain, you could do /@.*\\.com$. Note that +since the matching is done on the entire attribute value, +you can also use rules like /^[a−k].*@example\\.com$/ +to get some of the users in this domain to use one server, +while other users could be matched by another realm block +and use another server.</p> + +<p style="margin-left:11%; margin-top: 1em"><b>REALM BLOCK +OPTIONS</b> <br> +A realm block may contain none, one or multiple server +options. If defined, the values of the server options must +be the names of previously defined server blocks. Normally +requests will be forwarded to the first server option +defined. If there are multiple server options, the proxy +will do fail-over and use the second server if the first is +down. If the two first are down, it will try the third etc. +If say the first server comes back up, it will go back to +using that one. Currently detection of servers being up or +down is based on the use of StatusServer (if enabled), and +that TCP/TLS/DTLS connections are up.</p> + +<p style="margin-left:11%; margin-top: 1em">A realm block +may also contain none, one or multiple accountingServer +options. This is used exactly like the server option, except +that it is used for specifying where to send matching +accounting requests. The values must be the names of +previously defined server blocks. When multiple accounting +servers are defined, there is a failover mechanism similar +to the one for the server option.</p> + +<p style="margin-left:11%; margin-top: 1em">If there is no +server option, the proxy will if replyMessage is specified, +reply back to the client with an Access Reject message. The +message contains a replyMessage attribute with the value as +specified by the replyMessage option. Note that this is +different from having no match since then the request is +simply ignored. You may wonder why this is useful. One +example is if you handle say all domains under say .bv. Then +you may have several realm blocks matching the domains that +exists, while for other domains under .bv you want to send a +reject. At the same time you might want to send all other +requests to some default server. After the realms for the +subdomains, you would then have two realm definitions. One +with the name /@.*\\.bv$ with no servers, followed by one +with the name * with the default server defined. This may +also be useful for blocking particular usernames.</p> + +<p style="margin-left:11%; margin-top: 1em">If there is no +accountingServer option, the proxy will normally do nothing, +ignoring accounting requests. There is however an option +called accountingResponse. If this is set to on, the proxy +will log some of the accounting information and send an +Accounting-Response back. This is useful if you do not care +much about accounting, but want to stop clients from +retransmitting accounting requests. By default this option +is set to off.</p> + +<h2>TLS BLOCK +<a name="TLS BLOCK"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The TLS block +specifies TLS configuration options and you need at least +one of these if you have clients or servers using TLS/DTLS. +As discussed in the client and server block descriptions, a +client or server block may reference a particular TLS block +by name. There are also however the special TLS block names +default, defaultClient and defaultServer which are used as +defaults if the client or server block does not reference a +TLS block. Also note that a TLS block must be defined before +the client or server block that would use it. If you want +the same TLS configuration for all TLS/DTLS clients and +servers, you need just a single tls block named default, and +the client and servers need not refer to it. If you want all +TLS/DTLS clients to use one config, and all TLS/DTLS servers +to use another, then you would be fine only defining two TLS +blocks named defaultClient and defaultServer. If you want +different clients (or different servers) to have different +TLS parameters, then you may need to create other TLS blocks +with other names, and reference those from the client or +server definitions. Note that you could also have say a +client block refer to a default, even defaultServer if you +really want to.</p> + +<p style="margin-left:11%; margin-top: 1em">The available +TLS block options are CACertificateFile, CACertificatePath, +certificateFile, certificateKeyFile, certificateKeyPassword, +cacheExpiry, CRLCheck and policyOID. When doing RADIUS over +TLS/DTLS, both the client and the server present +certificates, and they are both verified by the peer. Hence +you must always specify certificateFile and +certificateKeyFile options, as well as +certificateKeyPassword if a password is needed to decrypt +the private key. Note that CACertificateFile may be a +certificate chain. In order to verify certificates, or send +a chain of certificates to a peer, you also always need to +specify CACertificateFile or CACertificatePath. Note that +you may specify both, in which case the certificates in +CACertificateFile are checked first. By default CRLs are not +checked. This can be changed by setting CRLCheck to on. One +can require peer certificates to adhere to certain policies +by specifying one or multiple policyOIDs using one or +multiple policyOID options.</p> + +<p style="margin-left:11%; margin-top: 1em">CA certificates +and CRLs are normally cached permanently. That is, once a CA +or CRL has been read, the proxy will never attempt to +re-read it. CRLs may change relatively often and the proxy +should ideally always use the latest CRLs. Rather than +restarting the proxy, there is an option cacheExpiry that +specifies how many seconds the CA and CRL information should +be cached. Reasonable values might be say 3600 (1 hour) or +86400 (24 hours), depending on how frequently CRLs are +updated and how critical it is to be up to date. This option +may be set to zero to disable caching.</p> + +<h2>REWRITE BLOCK +<a name="REWRITE BLOCK"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The rewrite +block specifies rules that may rewrite RADIUS messages. It +can be used to add, remove and modify specific attributes +from messages received from and sent to clients and servers. +As discussed in the client and server block descriptions, a +client or server block may reference a particular rewrite +block by name. There are however also the special rewrite +block names default, defaultClient and defaultServer which +are used as defaults if the client or server block does not +reference a block. Also note that a rewrite block must be +defined before the client or server block that would use it. +If you want the same rewrite rules for input from all +clients and servers, you need just a single rewrite block +named default, and the client and servers need not refer to +it. If you want all clients to use one config, and all +servers to use another, then you would be fine only defining +two rewrite blocks named defaultClient and defaultServer. +Note that these defaults are only used for rewrite on input. +No rewriting is done on output unless explicitly specified +using the rewriteOut option.</p> + +<p style="margin-left:11%; margin-top: 1em">The available +rewrite block options are addAttribute, addVendorAttribute, +removeAttribute, removeVendorAttribute and modifyAttribute. +They can all be specified none, one or multiple times.</p> + +<p style="margin-left:11%; margin-top: 1em">addAttribute is +used to add attributes to a message. The option value must +be on the form attribute:value where attribute is a +numerical value specifying the attribute. Simliarly, the +addVendorAttribute is used to specify a vendor attribute to +be added. The option value must be on the form +vendor:subattribute:value, where vendor and subattribute are +numerical values.</p> + +<p style="margin-left:11%; margin-top: 1em">The +removeAttribute option is used to specify an attribute that +should be removed from received messages. The option value +must be a numerical value specifying which attribute is to +be removed. Similarly, removeVendorAttribute is used to +specify a vendor attribute that is to be removed. The value +can be a numerical value for removing all attributes from a +given vendor, or on the form vendor:subattribute, where +vendor and subattribute are numerical values, for removing a +specific subattribute for a specific vendor.</p> + + +<p style="margin-left:11%; margin-top: 1em">modifyAttribute +is used to specify modification of attributes. The value +must be on the form attribute:/regexpmatch/replacement/ +where attribute is a numerical attribute type, regexpmatch +is regexp matching rule and replacement specifies how to +replace the matching regexp. Example usage:</p> + +<p style="margin-left:22%;">modifyAttribute +1:/^(.*)@local$/\1@example.com/</p> + +<h2>SEE ALSO +<a name="SEE ALSO"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em"><b>radsecproxy</b>(1), +<br> +Transport Layer Security (TLS) Encryption for RADIUS ⟨ +https://tools.ietf.org/html/rfc6614⟩</p> +<hr> +</body> +</html> diff --git a/doc/1.6/radsecproxy.html b/doc/1.6/radsecproxy.html new file mode 100644 index 0000000..ee3140f --- /dev/null +++ b/doc/1.6/radsecproxy.html @@ -0,0 +1,251 @@ +<!-- Creator : groff version 1.22.2 --> +<!-- CreationDate: Thu Sep 17 10:29:23 2015 --> +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" +"http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> +<meta name="generator" content="groff -Thtml, see www.gnu.org"> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<meta name="Content-Style" content="text/css"> +<style type="text/css"> + p { margin-top: 0; margin-bottom: 0; vertical-align: top } + pre { margin-top: 0; margin-bottom: 0; vertical-align: top } + table { margin-top: 0; margin-bottom: 0; vertical-align: top } + h1 { text-align: center } +</style> +<title>radsecproxy</title> + +</head> +<body> + +<h1 align="center">radsecproxy</h1> + +<a href="#NAME">NAME</a><br> +<a href="#SYNOPSIS">SYNOPSIS</a><br> +<a href="#DESCRIPTION">DESCRIPTION</a><br> +<a href="#OPTIONS">OPTIONS</a><br> +<a href="#SIGNALS">SIGNALS</a><br> +<a href="#FILES">FILES</a><br> +<a href="#SEE ALSO">SEE ALSO</a><br> + +<hr> + + +<h2>NAME +<a name="NAME"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy - a +generic RADIUS proxy that provides both RADIUS UDP and +TCP/TLS (RadSec) transport.</p> + +<h2>SYNOPSIS +<a name="SYNOPSIS"></a> +</h2> + + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="89%"> + + +<p style="margin-top: 1em">radsecproxy [−c +configfile] [−d debuglevel] [−f] [−i +pidfile] [−p] [−v]</p></td></tr> +</table> + +<h2>DESCRIPTION +<a name="DESCRIPTION"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy is +a <b>generic RADIUS proxy</b> that in addition to to usual +<b>RADIUS UDP</b> transport, also supports <b>TLS +(RadSec)</b>. The aim is for the proxy to have sufficient +features to be flexible, while at the same time to be small, +efficient and easy to configure. Currently the executable on +Linux is only about <i>48 KB</i>, and it uses about <i>64 +KB</i> (depending on the number of peers) while running.</p> + +<p style="margin-left:11%; margin-top: 1em">The proxy was +initially made to be able to deploy <b>RadSec</b> (RADIUS +over TLS) so that all RADIUS communication across network +links could be done using TLS, without modifying existing +RADIUS software. This can be done by running this proxy on +the same host as an existing RADIUS server or client, and +configure the existing client/server to talk to localhost +(the proxy) rather than other clients and servers +directly.</p> + +<p style="margin-left:11%; margin-top: 1em">There are +however other situations where a RADIUS proxy might be +useful. Some people deploy RADIUS topologies where they want +to route RADIUS messages to the right server. The nodes that +do purely routing could be using a proxy. Some people may +also wish to deploy a proxy on a site boundary. Since the +proxy <b>supports both IPv4 and IPv6</b>, it could also be +used to allow communication in cases where some RADIUS nodes +use only IPv4 and some only IPv6.</p> + +<h2>OPTIONS +<a name="OPTIONS"></a> +</h2> + + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="3%"> + + +<p style="margin-top: 1em"><b>−f</b></p></td> +<td width="8%"></td> +<td width="26%"> + + +<p style="margin-top: 1em"><i>Run in foreground</i></p></td> +<td width="52%"> +</td></tr> +</table> + +<p style="margin-left:22%; margin-top: 1em">By specifying +this option, the proxy will run in foreground mode. That is, +it won’t detach. Also all logging will be done to +stderr.</p> + +<p style="margin-left:11%;"><b>−d <debug +level></b></p> + +<p style="margin-left:22%; margin-top: 1em"><i>Debug +level</i></p> + +<p style="margin-left:22%; margin-top: 1em">This specifies +the debug level. It must be set to 1, 2, 3, 4 or 5, where 1 +logs only serious errors, and 5 logs everything. The default +is 2 which logs errors, warnings and a few informational +messages.</p> + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="3%"> + + +<p><b>−p</b></p></td> +<td width="8%"></td> +<td width="10%"> + + +<p><i>Pretend</i></p></td> +<td width="68%"> +</td></tr> +</table> + +<p style="margin-left:22%; margin-top: 1em">The proxy reads +configuration files and performs initialisation as usual, +but exits prior to creating any sockets. It will return +different exit codes depending on whether the configuration +files are okay. This may be used to verify configuration +files, and can be done while another instance is +running.</p> + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="3%"> + + +<p style="margin-top: 1em"><b>−v</b></p></td> +<td width="8%"></td> +<td width="20%"> + + +<p style="margin-top: 1em"><i>Print version</i></p></td> +<td width="58%"> +</td></tr> +</table> + +<p style="margin-left:22%; margin-top: 1em">When this +option is specified, the proxy will simply print version +information and exit.</p> + +<p style="margin-left:11%;"><b>−c <config file +path></b></p> + +<p style="margin-left:22%; margin-top: 1em"><i>Config file +path</i></p> + +<p style="margin-left:22%; margin-top: 1em">This option +allows you to specify which config file to use. This is +useful if you want to use a config file that is not in any +of the default locations.</p> + +<p style="margin-left:11%;"><b>−i <pid file +path></b></p> + +<p style="margin-left:22%; margin-top: 1em"><i>PID file +path</i></p> + +<p style="margin-left:22%; margin-top: 1em">This option +tells the proxy to create a PID file with the specified +path.</p> + +<h2>SIGNALS +<a name="SIGNALS"></a> +</h2> + + +<p style="margin-left:11%; margin-top: 1em">The proxy +generally exits on all signals. The exceptions are listed +below.</p> + +<table width="100%" border="0" rules="none" frame="void" + cellspacing="0" cellpadding="0"> +<tr valign="top" align="left"> +<td width="11%"></td> +<td width="9%"> + + +<p><b>SIGHUP</b></p></td> +<td width="2%"></td> +<td width="78%"> + + +<p>When logging to a file, this signal forces a reopen of +the log file.</p></td></tr> +</table> + +<p style="margin-left:11%;"><b>SIGPIPE</b></p> + +<p style="margin-left:22%; margin-top: 1em">This signal is +ignored.</p> + +<h2>FILES +<a name="FILES"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em"><b>/etc/radsecproxy.conf</b></p> + +<p style="margin-left:22%; margin-top: 1em">The default +configuration file.</p> + +<h2>SEE ALSO +<a name="SEE ALSO"></a> +</h2> + + + +<p style="margin-left:11%; margin-top: 1em">radsecproxy.conf(5), +radsecproxy-hash(1)</p> +<hr> +</body> +</html> |