diff options
| -rw-r--r-- | radsecproxy.1 | 19 | ||||
| -rw-r--r-- | radsecproxy.conf.5 | 122 |
2 files changed, 114 insertions, 27 deletions
diff --git a/radsecproxy.1 b/radsecproxy.1 index 83bbc62..db816c6 100644 --- a/radsecproxy.1 +++ b/radsecproxy.1 @@ -1,10 +1,10 @@ -.TH radsecproxy 1 "7 June 2007" +.TH radsecproxy 1 "22 December 2007" .SH "NAME" radsecproxy - a generic RADIUS proxy that provides both RADIUS UDP and TCP/TLS (RadSec) transport. .SH "SYNOPSIS" -radsecproxy [ -c configfile ] [ -d debuglevel ] [ -f ] [ -v ] +radsecproxy [ -c configfile ] [ -d debuglevel ] [ -f ] [ -p ] [ -v ] .sp .SH "DESCRIPTION" @@ -23,11 +23,11 @@ RADIUS server or client, and configure the existing client/server to talk to localhost (the proxy) rather than other clients and servers directly. .sp -There may however be other situations where a RADIUS proxy might be +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 firewall boundary. Since the proxy \fBsupports both IPv4 +a proxy on a site boundary. Since the proxy \fBsupports both IPv4 and IPv6\fR, it could also be used to allow communication in cases where some RADIUS nodes use only IPv4 and some only IPv6. @@ -49,6 +49,17 @@ logs only serious errors, and 4 logs everything. The default is 3 which logs errors, warnings and some informational messages. .TP +.B -p +.sp +\fIPretend\fR +.sp +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. + +.TP .B -v .sp \fIPrint version\fR diff --git a/radsecproxy.conf.5 b/radsecproxy.conf.5 index 8d7e246..faa0bee 100644 --- a/radsecproxy.conf.5 +++ b/radsecproxy.conf.5 @@ -1,4 +1,4 @@ -.TH radsecproxy.conf 5 "13 June 2007" +.TH radsecproxy.conf 5 "22 December 2007" .SH "NAME" radsecproxy.conf - Radsec proxy configuration file @@ -15,7 +15,9 @@ If -c option isn't used the proxy will read the file \fBradsecproxy.conf\fR in the \fBcurrent directory\fR. .sp If the configuration file can not be found, the proxy will exit with an error -message. +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. .SH "CONFIGURATION SYNTAX" When the configuration file is processed, whitespace (spaces and tabs) are @@ -58,6 +60,21 @@ blocktype name { } .fi .LP +.sp +There is one special option that can be used both as a basic option and inside all +blocks. That is the option \fBInclude\fR 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.: +.IP +.nf +include /etc/radsecproxy.conf.d/*.conf +.fi +.LP +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 \fBInclude\fR option. Included files may again include other files. +.sp .SH "BASIC OPTIONS" The following basic options may be specified in the configuration file. Note that @@ -106,6 +123,27 @@ you specify port number. This is similar to the \fBListenUDP\fR option, except that it used for receiving connections from TCP clients. The default port number is \fB2083\fR. .sp +.TP +\fBListenAccountingUDP\fR +This is similar to the \fBListenUDP\fR option, except that it used for specifying +port and optionally the address to receive UDP Accounting messages on. +.sp +.TP +\fBSourceUDP\fR +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). +.sp +.TP +\fBSourceTCP\fR +This can be used to specify source address and/or source port that the proxy +will use for sending TCP client messages (e.g. Access Request). +.sp +.TP +\fBInclude\fR +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. +.sp .SH "BLOCKS" There are four types of blocks, they are \fBClient\fR, \fBServer\fR, \fBRealm\fR @@ -122,21 +160,36 @@ name must be previously defined. Hence the order of the blocks may be significan .SH "CLIENT BLOCK" 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 \fBname\fR of the -client block must be either the IP address (IPv4 or IPv6) of the client, 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. 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, to determine which -(if any) of the clients this is. In the case of TLS, the name of the client must -match the FQDN or IP address in the client certificate. -.sp -The allowed options in a client block are \fBtype\fR, \fBsecret\fR, \fBtls\fR -and \fBmatchcertificateattribute\fR. +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) of the form +IpAddress/PrefixLength, or a domain name (FQDN). +.sp +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. +.sp +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. +.sp +In the case of TLS, 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. +.sp +Alternatively one may use the \fBhost\fR option inside a client block. In that +case, the value of the \fBhost\fR option is used as above, while the name of the +block is only used as a descriptive name for the administrator. +.sp +The allowed options in a client block are \fBhost\fR, \fBtype\fR, \fBsecret\fR, +\fBtls\fR, \fBmatchcertificateattribute\fR and \fBrewriteattribute\fR. We already +discussed the \fBhost\fR option. The value of \fBtype\fR must be either \fBudp\fR or \fBtls\fR. The value of \fBsecret\fR 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. +.sp For a TLS client you may also specify the \fBtls\fR 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 \fBdefaultclient\fR will be used if defined. If not @@ -148,11 +201,22 @@ certain values. Currently the allowed values are of the form SubjectAltName:URI:/regexp/ which can be used to specify that SubjectAltName URIs in the certificate match the specified regexp. .sp +The \fBrewriteattribute\fR 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 of the form User-Name:/regexpmatch/replacement/. Example usage: +.IP +.nf +rewriteattribute User-Name:/^(.*)@local$/$1@example.com/ +.fi +.LP .SH "SERVER BLOCK" 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 \fBname\fR of the server block must be either the IP address (IPv4 or IPv6) +The \fBname\fR 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. @@ -162,14 +226,20 @@ will loop through the addresses until it can connect to one of them. In the case of TLS, the name of the server must match the FQDN or IP address in the server certificate. .sp -The allowed options in a server block are \fBtype\fR, \fBsecret\fR, \fBtls\fR, -\fBport\fR, \fBstatusServer\fR and \fBmatchcertificateattribute\fR. The values +Alternatively one may use the \fBhost\fR option inside a server block. In that +case, the value of the \fBhost\fR option is used as above, while the name of the +block is only used as a descriptive name for the administrator. +.sp +The allowed options in a server block are \fBhost\fR, \fBport\fR, \fBtype\fR, +\fBsecret\fR, \fBtls\fR, \fBstatusServer\fR and \fBmatchcertificateattribute\fR. +We already discussed the \fBhost\fR option. +The \fBport\fR option allows you to specify which port number the server uses. +The values of \fBtype\fR, \fBsecret\fR, \fBtls\fR and \fBmatchcertificateattribute\fR are just as specified for the \fIclient block\fR above, except that \fBdefaultserve\fRr (and not \fBdefaultclient\fR) is used as a fallback if the \fBtls\fR option is not used. .sp -The \fBport\fR option allows you to specify which port number the server uses. \fBstatusServer\fR can be specified to enable the use of statusServer messages for this server. The value must be either \fBon\fR or \fBoff\fR. The default when not specified, is \fBoff\fR. If statusServer is enabled, the proxy will @@ -183,8 +253,8 @@ 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 at most one \fBserver\fR option, and at most -one \fBreplyMessage\fR option. We will discuss these later. +found. A realm block may contain none, one or multiple \fBserver\fR options, +and optionally a \fBreplyMessage\fR option. We will discuss these later. .sp .TP @@ -218,9 +288,15 @@ could be matched by another realm block and use another server. .TP \fBRealm block options\fR .sp -A realm block may contain at most one \fBserver\fR option. If defined, the -value of the \fBserver\fR option must be the name of a previously defined -server block, and this will be the server that the request is forwarded to. +A realm block may contain none, one or multiple \fBserver\fR options. If +defined, the values of the \fBserver\fR 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 TLS connections are up. .sp If there is no \fBserver\fR option, the proxy will reply back to the client with an Access Reject message. Note that this is different from having no |