auth.sgml

gnugk软交换产品

<descrip>
<tag/Format:/
<tscreen><verb>
prefix=authrule[|authrule|...]
</verb></tscreen>

<tag/Syntax:/
<tscreen><verb>
&lt;authrule&gt; :=  &lt;result&gt; &lt;authrule&gt;

  &lt;result&gt;    := deny | allow
  &lt;authrule&gt;  := [!]ipv4:&lt;iprule&gt; | [!]alias:&lt;aliasrule&gt;
</verb></tscreen>
</descrip>
Where <tt/&lt;iprule&gt;/ can be specified in decimal dot notation or
CIDR notation, <tt/&lt;aliasrule&gt;/ is expressed in regular expression.
If the `<tt/!/' flag precedes the rule, the sense is inverted.

<descrip>
<tag/Example:/
<tscreen><verb>
555=deny ipv4:10.0.0.0/27|allow ipv4:0/0
5555=allow ipv4:192.168.1.1|deny ipv4:192.168.1.0/255.255.255.0
86=deny !ipv4:172.16.0.0/24
09=deny alias:^188884.*
ALL=allow ipv4:ALL
</verb></tscreen>
</descrip>

In this configuration, all endpoints except from network <tt>10.0.0.0/27</tt>
are allow to call prefix 555 (except 5555).
Endpoints from <tt>192.168.1.0/24</tt> are not allowed to call prefix 5555,
except <tt/192.168.1.1/.
Endpoints <bf/not/ from <tt>172.16.0.0/24</tt> are denied to call prefix 86.
Endpoints having an alias beginning with 188884 are not allowed to call
prefix 09. All other situations are allowed.

<sect1>Section &lsqb;RadAuth&rsqb;
<label id="radauth">
<p>
This section defines configuration settings that enable
RADIUS authentication based on H.235 CATs (Cisco Access Tokens)
present in RRQ, ARQ RAS requests and Q.931 Setup messages.
<itemize>
<item><tt/Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];.../<newline>
Default: <tt>N/A</tt>
<p>
RADIUS servers to be used for authentication. The list can contain an arbitrary 
number of servers. The order of servers is important, because servers will 
be queried by the RADIUS module in the given order. If no port information 
is provided, port number from <tt/DefaultAuthPort/ will be used. If no secret is set, 
the default shared secret from <tt/SharedSecret/ is taken. 
Servers names can be IP addresses or DNS names.

<descrip>
<tag>Sample <tt/Servers/ lines:</tag>
<tt>Servers=192.168.1.1</tt><newline>
<tt>Servers=192.168.1.1:1645</tt><newline>
<tt>Servers=192.168.1.1:1645:1646:secret1</tt><newline>
<tt>Servers=radius1.mycompany.com:1812</tt><newline>
<tt>Servers=radius1.mycompany.com;radius2.mycompany.com</tt><newline>
<tt>Servers=radius1.mycompany.com:1812:1813:secret1;radius2.mycompany.com:1812:1813:secret2</tt><newline>
</descrip>

<item><tt/LocalInterface=IP_OR_FQDN/<newline>
Default: <tt>N/A</tt>
<p>
Particular local network interface that RADIUS client should
use in order to communicate with RADIUS servers. This parameter
can be useful on NAT machines to restrict number of network
interfaces used for RADIUS communication. By default this value
is empty and allows RADIUS requests to be sent on any (best suitable)
network interface. If you are not sure what you are doing, it is
better to leave this option unset.

<item><tt/RadiusPortRange=10000-11000/<newline>
Default: <tt>N/A</tt>
<p>
By default (if this option is not set) RADIUS client
allocates ports dynamically as specified by the operating system.
If you want to restrict RADIUS client to use ports from
a particular range only - set this parameter.

<item><tt/DefaultAuthPort=PORT_NO/<newline>
Default: <tt>1812</tt>
<p>
Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overriden by <tt/Servers/ attribute.

<item><tt/SharedSecret=SECRET/<newline>
Default: <tt>N/A (empty string)</tt>
<p>
Secret used to authenticate this GnuGk (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used, if no server-specific secret is set in the <tt/Servers/.
If <tt/EncryptAllPasswords/ is enabled, or a <tt/KeyFilled/ variable is defined
in this section, the password is in encrypted form and should be created using
the <tt/addpasswd/ utility.

<item><tt/RequestTimeout=TIMEOUT_MS/<newline>
Default: <tt/2000/ (miliseconds)
<p>
Timeout (miliseconds) for RADIUS server response to a request
sent by GnuGk. If no response is received within this time period,
next RADIUS server is queried.

<item><tt/IdCacheTimeout=TIMEOUT_MS/<newline>
Default: <tt/9000/ (miliseconds)
<p>
Timeout (miliseconds) for RADIUS request 8-bit identifiers to be
unique. If all 8-bit identifier range is exhausted within this period,
new client socket (UDP socket) is allocation by RADIUS module. Let's
take the example: we have approximatelly 60 RRQs/sec - after ca. 4 seconds
8-bit identifiers range gets exhausted - new socket allocated - after next
4 seconds the second 8-bit identifiers range gets exhauted - third socket
allocated - after 9th second identifiers from the pool 1 are available again
- ... . In general, too long timeout - too much resources consumed,
too short timeout - RADIUS server may take incoming packets as duplicated
and therefore drop it.

<item><tt/SocketDeleteTimeout=TIMEOUT_MS/<newline>
Default: <tt/60000/ (miliseconds) - 60 s
<p>
Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <tt/IdCacheTimeout/ - additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.

<item><tt/RequestRetransmissions=NUMBER/<newline>
Default: <tt/2/
<p>
How many times a single RADIUS request is transmissed to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by <tt/RoundRobinServers/ attribute.

<item><tt/RoundRobinServers=BOOLEAN/<newline>
Default: <tt/1/
<p>
RADIUS requests retransmission method.
<p>
If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<tscreen><verb>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</verb></tscreen>
<p>
If set to 0, the following sequence is preserved:
<tscreen><verb>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</verb></tscreen>

<item><tt/AppendCiscoAttributes=BOOLEAN/<newline>
Default: <tt/0/
<p>
If set, Cisco Vendor Specific RADIUS attibutes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).

<item><tt/IncludeTerminalAliases=BOOLEAN/<newline>
Default: <tt/1/
<p>
If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<tscreen><verb>
	Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
	Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</verb></tscreen>

<item><tt/UseDialedNumber=BOOLEAN/<newline>
Default: <tt/0/
<p>
Select Called-Station-Id number type between the original one (as dialed
by the user) - <tt/UseDialedNumber=1/ - and the rewritten one - <tt/UseDialedNumber=0/.

</itemize>

<sect1>Section &lsqb;RadAliasAuth&rsqb;
<label id="radaliasauth">
<p>
This section defines configuration settings that enable
RADIUS authentication based on endpoint aliases and/or IP adresses
present in RRQ RAS requests, ARQ RAS request or Q.931 Setup request.
This authentication scheme is useful both for endpoints registered
at the gatekeeper (ARQ,RRQ) and calls from unregistered endpoints (Setup).

<itemize>
<item><tt/Servers=SERVER1[:AUTH_PORT[:ACCT_PORT[:SECRET]]];SERVER2[:AUTH_PORT[:ACCT_PORT[:SECRET]]];.../<newline>
Default: <tt>N/A</tt>
<p>
RADIUS servers to be used for RAS requests authentication.
This list can contain an arbitrary number of servers. The order of servers 
is important, because servers will be queried by the RADIUS module 
in the given order. If no port information is specified, port number from 
<tt/DefaultAuthPort/ will be used. If no secret is set, 
the default shared secret from <tt/SharedSecret/ is used.
Servers can be IP addresses or DNS names.

<descrip>
<tag/Example:/
<tt/Servers=192.168.3.1:1645;192.168.3.2:1812:1813:mysecret;radius.mycompany.com/
</descrip>

<item><tt/LocalInterface=IP_OR_FQDN/<newline>
Default: <tt>N/A</tt>
<p>
Particular local network interface that RADIUS client should
use in order to communicate with RADIUS servers. This parameter
can be useful on NAT machines to restrict number of network
interfaces used for RADIUS communication. By default this value
is empty and allows RADIUS requests to be sent on any (best suitable)
network interface. If you are not sure what you are doing, it is
better to leave this option unset.

<item><tt/RadiusPortRange=10000-11000/<newline>
Default: <tt>N/A</tt>
<p>
By default (if this option is not set) RADIUS client
allocates ports dynamically as specified by the operating system.
If you want to restrict RADIUS client to use ports from
a particular range only - set this parameter.

<item><tt/DefaultAuthPort=PORT_NO/<newline>
Default: <tt>1812</tt>
<p>
Default port number to be used for RADIUS authentication requests
(Access-Request packets), if not overriden by <tt/Servers/ attribute.

<item><tt/SharedSecret=SECRET/<newline>
Default: <tt>N/A (empty string)</tt>
<p>
Secret used to authenticate this GNU GK (NAS client) to RADIUS
server. It should be a cryptographically strong password. This is the default
value used, if no server-specific secret is set in the <tt/Servers/.
If <tt/EncryptAllPasswords/ is enabled, or a <tt/KeyFilled/ variable is defined
in this section, the password is in encrypted form and should be created using
the <tt/addpasswd/ utility.

<item><tt/RequestTimeout=TIMEOUT_MS/<newline>
Default: <tt/2000/ (miliseconds)
<p>
Timeout (miliseconds) for RADIUS server response to a request
sent by GNU GK. If no response is received within this time period,
next RADIUS server is queried.

<item><tt/IdCacheTimeout=TIMEOUT_MS/<newline>
Default: <tt/9000/ (miliseconds)
<p>
Timeout (miliseconds) for RADIUS request 8-bit identifiers to be
unique. If all 8-bit identifier range is exhausted within this period,
new client socket (UDP socket) is allocation by RADIUS module. Let's
take the example: we have approximatelly 60 RRQs/sec - after ca. 4 seconds
8-bit identifiers range gets exhausted - new socket allocated - after next
4 seconds the second 8-bit identifiers range gets exhauted - third socket
allocated - after 9th second identifiers from the pool 1 are available again
- ... . In general, too long timeout - too much resources consumed,
too short timeout - RADIUS server may take incoming packets as duplicated
and therefore drop it.

<item><tt/SocketDeleteTimeout=TIMEOUT_MS/<newline>
Default: <tt/60000/ (miliseconds) - 60 s
<p>
Timeout for unused RADIUS sockets to be closed. It is used
in conjunction with <tt/IdCacheTimeout/ - additional sockets
created during heavy GK load time periods for serving incoming
requests are closed during idle periods.

<item><tt/RequestRetransmissions=NUMBER/<newline>
Default: <tt/2/
<p>
How many times a single RADIUS request is transmissed to every
configured RADIUS server (if no response is received). 1 means
no retransmission, 2 - single retransmission, ... . Exact retransmission
method is defined by <tt/RoundRobinServers/ attribute.

<item><tt/RoundRobinServers=BOOLEAN/<newline>
Default: <tt/1/
<p>
RADIUS requests retransmission method.
<p>
If set to 1, RADIUS request
is transmitted in the following way (until response is received):
<tscreen><verb>
Server #1 Attempt #1, Server #2 Attempt #1, ..., Server #N Attempt #1
...
Server #1 Attempt #RequestRetransmissions, ..., Server #1 Attempt #RequestRetransmissions
</verb></tscreen>
<p>
If set to 0, the following sequence is preserved:
<tscreen><verb>
Server #1 Attempt #1, ..., Server #1 Attempt #RequestRetransmissions
...
Server #N Attempt #1, ..., Server #N Attempt #RequestRetransmissions
</verb></tscreen>

<item><tt/AppendCiscoAttributes=BOOLEAN/<newline>
Default: <tt/1/
<p>
If set, Cisco Vendor Specific RADIUS attibutes are included
in RADIUS requests (h323-conf-id,h323-call-origin,h323-call-type).

<item><tt/IncludeTerminalAliases=BOOLEAN/<newline>
Default: <tt/1/
<p>
If set, Cisco VSA 'h323-ivr-out' attribute is sent with a list of aliases
the endpoint is registering (RRQ.m_terminalAlias). This attribute is provided
in order to provide fine control over the list of aliases the endpoint
is allowed to register with. Format of this attribute is:
<tscreen><verb>
	Cisco-AV-Pair = "h323-ivr-out=terminal-alias:" alias [,alias] [;]
Example:
	Cisco-AV-Pair = "h323-ivr-out=terminal-alias:helpdesk,support,77771;"
</verb></tscreen>

<item><tt/FixedUsername/<newline>
Default: <tt>N/A</tt>
<p>
If this parameter is set, it overwrites a value of User-Name RADIUS attribute
for outgoing RADIUS request. That means every Access-Request will be
authenticated as for user <tt/FixedUsername/.

<item><tt/FixedPassword/<newline>
Default: <tt>N/A</tt>
<p>
If not set, User-Password is a copy of User-Name. For example, if User-Name
is 'john' then User-Password will also be set to 'john'. Setting this
parameter overrides this behavious and User-Password attribute will be
always set to the value of <tt/FixedPassword/.
If <tt/EncryptAllPasswords/ is enabled, or a <tt/KeyFilled/ variable is defined
in this section, the password is in encrypted form and should be created using
the <tt/addpasswd/ utility.

<descrip>
<tag/Example 1:/
<tscreen><verb>
(Neither FixedUsername nor FixedPassword set)
</verb></tscreen>
All endpoints will be authenticated using their alias as the username
and the password. That means, for example, endpoint 'EP1' will be authenticated
with the username 'EP1 and the password 'EP1'.
</descrip>

<descrip>
<tag/Example 2:/
<tscreen><verb>
(FixedUsername not set)
FixedPassword=ppp
</verb></tscreen>
All endpoints will be authenticated using their alias and the password 'ppp'.
</descrip>

<descrip>
<tag/Example 3:/
<tscreen><verb>
FixedUsername=ppp
FixedPassword=ppp
</verb></tscreen>
All endpoints will be authenticated using the username 'ppp'
and the password 'ppp'.
</descrip>

<item><tt/UseDialedNumber=BOOLEAN/<newline>
Default: <tt/0/
<p>
Select Called-Station-Id number type between the original one (as dialed
by the user) - <tt/UseDialedNumber=1/ - and the rewritten one - <tt/UseDialedNumber=0/.

</itemize>