Smarter by Design.Simpler for Business
ags authentication-server
The ags authentication-server command manages the connection definition of the directory or the service that AGS will connect to for the authentication: the protocol, the server addresses, the load distribution, the connection and TLS settings. Its panel equivalent is the Authentication Servers screen.
This record says only where the connection will be made. How the identity will be verified is a separate record and is defined with ags authentication-provider; the provider binds to this server with the authServerId field.
Command Summary
admin@TR7LBWAF01> ags authentication-server list # list all of them
admin@TR7LBWAF01> ags authentication-server show <id> # show one
admin@TR7LBWAF01> ags authentication-server add name <name> protocol <protocol> … # new record
admin@TR7LBWAF01> ags authentication-server update id <id> … # change
admin@TR7LBWAF01> ags authentication-server delete <id> # delete
admin@TR7LBWAF01>
Writing Order
Step 1 Write the name
ags authentication-server add name corporate-ldapThe name is unique and the provider record lists this server by its name.
Step 2 Select the protocol
protocol ldapIt takes five values:
ldap, ldaps, radius, http, https. The selected protocol determines which settings are valid afterwards. Step 3 Give at least one server address
--hosts.0.host 10.0.0.30 --hosts.0.port 389The addresses are a list field, so they are written with the
-- prefix and with an index. They do not appear as required in the completion list, but without at least one address being given the record is not formed. Step 4 Add the settings if needed
All of the connection, TLS and load balancing settings are optional and work with their default values.
The RADIUS secret is not written on the command line
When the radius protocol is selected the RADIUS shared secret field is required, but it is not written on the command line: after Enter is pressed it is asked for on a separate line, without appearing on the screen. For this reason no such field appears in the command.
Required Fields
The fields below are all required: the CLI asks for them in the given order, one by one, and without one being written it does not show the next.
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The unique name of the server |
| 2 | protocol | Required | ldap · ldaps · radius · http · https |
| 3 | radiusSecret | Conditionally required | Only in the radius protocol; it is asked for secretly after the command |
| — | --hosts.0.host · --hosts.0.port | At least one address | It appears as optional in the completion list, but a record without an address is not accepted |
The Server Addresses
A server record can carry more than one address; each address is written with its own index and has three fields.
| Field | Value |
|---|---|
--hosts.N.host | The address of the server |
--hosts.N.port | The connection port |
--hosts.N.weight | The weight; between 1 and 10, default 1 |
When more than one address is given, the requests are distributed according to the --lbMethod field:
| Value | Behavior |
|---|---|
roundrobin | Distributes in order (default) |
weighted | Distributes according to the weights |
failover | Uses the first address and, if it is unreachable, moves to the next |
Optional Fields
| Field | Default | The protocols it is valid in |
|---|---|---|
--lbMethod | roundrobin | All |
--disableHealthCheck | false | All |
--namespace | The default route table of the device | ldap ldaps radius http https |
--connectionTimeout | 30 seconds (1–300) | ldap ldaps radius http https |
--connectionPoolSize | 5 (1–50) | ldap ldaps radius http https |
--sslValidateCertificate | true | Only ldaps and https |
--sslMinTlsVersion | 1.2 (1.2 or 1.3) | Only ldaps and https |
The --namespace field determines the route table over which the server will be reached; in the panel this field appears under the name Route table.
Examples
admin@TR7LBWAF01> ags authentication-server add name corporate-ldap protocol ldap \
--hosts.0.host 10.0.0.30 --hosts.0.port 389
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags authentication-server add name corporate-ldaps protocol ldaps \
--hosts.0.host 10.0.0.30 --hosts.0.port 636 --hosts.0.weight 3 \
--hosts.1.host 10.0.0.31 --hosts.1.port 636 --hosts.1.weight 1 \
--lbMethod weighted --sslMinTlsVersion 1.3
admin@TR7LBWAF01>
admin@TR7LBWAF01> ags authentication-server add name radius-01 protocol radius \
--hosts.0.host 10.0.0.40 --hosts.0.port 1812
RADIUS shared secret: ••••••••
admin@TR7LBWAF01>
Updating and Deleting
The update asks for the identity with the id field and changes only the fields that are written. The address list is updated with the index; --hosts.delete empties the whole list.
admin@TR7LBWAF01> ags authentication-server update id <id> --connectionTimeout 60
admin@TR7LBWAF01> ags authentication-server update id <id> --hosts.1.host 10.0.0.32 # change the second address
admin@TR7LBWAF01> ags authentication-server delete <id>
admin@TR7LBWAF01>
While a record whose protocol is radius is being updated, since the secret is not read back from the old record it is asked for again.
Things to Know
- There is no connection test on the command line. The Test Connection operation in the server preview of the panel has no CLI equivalent; the connection cannot be tested with this command.
- A record without an address is not formed. Even though the address fields appear as optional in the completion list, the server expects at least one address; a command run without an address returns an error.
- The settings appear according to the protocol. The TLS settings are listed only in the
ldapsandhttpsprotocols, and the connection and route table settings in all five protocols. - The usage should be checked before deleting. If there is a provider bound to this server the record is still deleted; the breaking of the bond is seen on the provider side.
