TACACS+ NG

4.2.1.1. Limits and timeouts

A number of global limits and timeouts may be specified exclusively at global level:

• retire limit = n

  The particular daemon instance will terminate after processing n requests. The spawnd instance will spawn a new instance if necessary.

  Default: unset

• retire timeout = s

  The particular daemon instance will terminate after s seconds. spawnd will spawn a new instance if necessary.

  Default: unset

	Time units
	Appending s, m, h or d to any timeout value will scale the value as expected.

4.2.1.2. DNS

tac_plus-ng can make use of both static and dynamic (via c-ares) DNS entries. Configuration options at global (and realm) level are:

• dns preload address address = hostname

  Preload DNS cache with address-to-hostname mapping.

• dns preload file = filename

  Preload DNS cache with address-to-hostname mappings from filename (see your hosts(5) manpage for syntax).

  Example:

  dns preload address 1.2.3.4 = router.example.com
  dns preload file = /etc/hosts
  
  device router.example.com {
      # "address = 1.2.3.4" is implied
      key = mykey
  }

• dns cache period = seconds

  This option specifies the minimum DNS response caching time (default: 1800 seconds).

• dns servers = "string"

  This option specifies the servers to use. This string will be evaluated by ares_set_servers_ports_csv(3), please see the corresponding man page for details. The option isn't available if compiled without DNS support.

The following configuration options are available at global, realm, device and net level.

• dns reverse-lookup [ nac | nas ] = ( yes | no )

  This will perform a DNS reverse lookup on the NAC address, the NAS address or (if unspecified) both.

• dns timeout = seconds

  This option specifies the maximum amount of time to wait for a DNS response.

4.2.1.3. Process-specific options

There are a couple of process-specific options available:

• coredump directory = directory

  Dump cores to directory. You really shouldn't need this.

4.2.1.4. Railroad Diagrams

4.2.2.1. Railroad Diagrams

4.2.3.1. Logging

Logging options defined in the top-level default realm will be shared with sub-realms unless the sub-realm has its own logging configuration. The software provides logs for

• Authentication

    authentication log = log_destination

• Authorization

    authorization log = log_destination

• Accounting

    accounting log = log_destination

• Connections

    connection log = log_destination

Logs may be written to multiple destinations:

Valid log destinations are "named":

  log mylog {
    destination = 169.254.0.23                     # UDP syslog
    # or one of the following:
    # destination = [fe80::123:4567:89ab:cdef]:514 # IPv6 UDP, with non-standard UDP port
    # destination = "/tmp/x.log"                   # plain file, async writes
    # destination = ">/tmp/x.log"                  # plain file, sync writes
    # destination = "|my_script.sh"                # script
    # destination = syslog                         # syslog(3)
    #
    syslog facility = MAIL                         # sets log facility
    syslog level = DEBUG                           # sets log level
  }
  authentication log = mylog
  accounting log = mylog
  authorization log = mylog

	Syslog
	Logging non-session related output to syslogd(8) can be disabled using syslog default = deny

Log destinations may contain strftime(3)-style character sequences, e.g.:

      destination = /var/log/tac_plus/%Y/%m/%d.auth

to automate time-based log file switching. By default, the daemon will use your local time zone for time conversion. You can switch to a different one by using the time zone option (see below).

A couple of other configuration options that may be useful in log context include:

• ( authentication | authorization | accounting ) format = string

  This defines the logging format. strftime(3) conversions are recognized. The following variables are resolved:

  ${cmd}, ${cmd,separator}	values of cmd= and cmd-arg= attribute-value pairs, separated by whitespace or separator. Will be mapped to ${args} if service isn't shell
  ${args}, ${args,separator}	input attribute-value pairs (excluding service, separated by whitespace or separator
  ${rargs}, ${rargs,separator}	output attribute value pairs, separated by whitespace or separator
  ${device.address}, ${nas} [deprecated]	Device IP address
  ${client}, ${nac}	Client IP address
  ${user}	user name
  ${profile}	profile assigned to user
  ${service}	service type (e.g. shell)
  ${result}	typically permit or deny
  ${device.port}${port} [deprecated]	NAS port (console, tty, ...)
  ${hint}	added/replaced for authorization, informal text for accounting
  ${device.name}, ${host} [deprecated]	Device name of matching device declaration
  ${client.dnsname}, ${nac-name} [deprecated]	Client DNS reverse mapping
  ${device.dnsname}, ${nas-name} [deprecated]	Device DNS reverse mapping
  ${msgid}	A message ID, perhaps suitable for RFC5424 logs. These are listed somewhere below.
  ${type}	packet type (authen/author/acct)
  ${accttype}	accounting type (start/stop/update)
  ${priority}	syslog priority
  ${action}	authentication info (e.g. pap login)
  ${privlvl}	privilege level
  ${authen-action}	login or chpass
  ${authen-type}	Authentication packet type, e.g. AUTHEN/PASS, AUTHEN/FAIL
  ${authen-service}	asciiascii/pap/chap/mschap/mschapv2
  ${authen-method}	krb5/line/enable/local/tacacs+/guest/radius/krb4/rcmd
  ${rule}	Name of the matching rule.
  ${label}	Ruleset label, if any.
  ${config-file}	Configuration file name
  ${config-line}	Configuration file line number
  ${context}	Context variable (set via context = ...)
  ${vrf}	Name of the current socket IPv4 vrf, supported on Linux (requires sysctl net.ipv4.tcp_l3mdev_accept=1) and possibly OpenBSD.
  ${realm}	realm name
  ${uid}	UID from PAM backend
  ${gid}	GID from PAM backend
  ${gids}	GIDs from PAM backend
  ${home}	Home directory from PAM backend
  ${shell}	Shell from PAM backend
  ${dn}	Raw dn backend value, typically from LDAP
  ${identity-source}	The IDENTITY_SOURCE backend value (the identitySourceName of the originating MAVIS module)
  ${memberof}	Raw memberOf backend value, typically from LDAP
  ${server.name}, ${hostname} [deprecated]	Server host name
  ${server.address}	Server address
  ${server.port}	Server TCP port
  ${tls.conn.version}	TLS Connection Version (requires LibTLS or OpenSSL)
  ${tls.conn.cipher}	TLS Connection Cipher (requires LibTLS or OpenSSL)
  ${tls.peer.cert.issuer}	TLS Peer Certificate Issuer (requires LibTLS or OpenSSL)
  ${tls.peer.cert.subject}	TLS Peer Certificate Subject (requires LibTLS)
  ${tls.conn.cipher.strength}	TLS Connection Cipher Strength (requires LibTLS or OpenSSL)
  ${tls.peer.cn}	TLS peer certificate Common Name (requires LibTLS or OpenSSL)
  ${tls.psk.identity}	TLS PSK identity (requires OpenSSL)

  The built-in defaults as of writing this are:

  # Accounting to file/pipe:
  "%Y-%m-%d %H:%M:%S %z\t${nas}\t${user}\t${port}\t${nac}\t${accttype}\t${service}\t${cmd}\n"
  # Accounting to UDP syslog:
  "<${priority}>%Y-%m-%d %H:%M:%S %z ${hostname} ${nas}|${user}|${port}|${nac}|${accttype}|${service}|${cmd}"
  # Accounting to syslog(3):
  "${nas}|${user}|${port}|${nac}|${accttype}|${service}|${cmd}"
  # Authorization to file/pipe:
  "%Y-%m-%d %H:%M:%S %z\t${nas}\t${user}\t${port}\t${nac}\t${profile}\t${result}\t${service}\t${cmd}\n"
  # Authorization to UDP syslog:
  "<${priority}>%Y-%m-%d %H:%M:%S %z ${hostname} ${nas}|${user}|${port}|${nac}|${profile}|${result}|${service}|${cmd}"
  # Authorization to syslog(3):
  "${nas}|${user}|${port}|${nac}|${profile}|${result}|${service}|${cmd}"
  # Authentication to file/pipe:
  "%Y-%m-%d %H:%M:%S %z\t${nas}\t${user}\t${port}\t${nac}\t${action} ${hint}\n"
  # Authentication to UDP syslog:
  "<${priority}>%Y-%m-%d %H:%M:%S %z ${hostname} ${nas}|${user}|${port}|${nac}|${action} ${hint}"
  # Authentication to syslog(3):
  "${nas}|${user}|${port}|${nac}|${action} ${hint}"
  # Connections to file/pipe:
  "%Y-%m-%d %H:%M:%S %z\t${accttype}\t${nas}\t${tls.conn.version}\t${tls.peer.cert.issuer}\t${tls.peer.cert.subject}\n"
  # Connections to UDP syslog:
  "<${priority}>%Y-%m-%d %H:%M:%S %z ${hostname} ${accttype}|${nas}|${tls.conn.version}|${tls.peer.cert.issuer}|${tls.peer.cert.subject}"
  # Connections to syslog(3):
  "${accttype}|${nas}|${tls.conn.version}|${tls.peer.cert.issuer}|${tls.peer.cert.subject}"

  Message ID	Description
  AUTHZPASS	authorization succeeded
  AUTHZPASS-ADD	authorization succeeded, attribute-value-pairs were added
  AUTHZPASS-REPL	authorization succeeded, attribute-value-pairs were replaced
  AUTHZFAIL	authorization failed
  AUTHCFAIL	generic authentication failure
  AUTHCFAIL-ABORT	authentication was aborted
  AUTHCFAIL-BACKEND	the authentication backend failed
  AUTHCFAIL-BUG	authentication failed due some programming error
  AUTHCFAIL-DENY	authentication was denied
  AUTHCFAIL-WEAKPASSWORD	the password used didn't met minimum criteria
  AUTHCFAIL-ACL	access was denied due to ruleset or acl
  AUTHCFAIL-DENY-RETRY	the user tried the same wrong password once more
  AUTHCFAIL-PASSWORD-NOT_TEXT	the password isn't specified as clear-text
  AUTHCFAIL-BAD-CHALLENGE-LENGTH	the MSCHAP challenge length didn't match
  AUTHCFAIL-NOPASS	there's no passwort set for the user
  AUTHCPASS	authentication passed
  ACCT-START	accounting start
  ACCT-STOP	accounting stop
  ACCT-UNKNOWN	unknown (non-compliant) accounting data
  ACCT-UPDATE	accounting update/watchdog
  CONN-REJECT	connection was rejected
  CONN-START	connection was started
  CONN-STOP	connection was terminated

• time zone = time-zone

  By default, the daemon uses your local system time zone to convert the internal system time to calendar time. This option sets the TZ environment variable to the time-zone argument. See your local tzset man page for details.

• umask = mode

  This sets the file creation mode mask. Example:

  umask = 0640

1995-07-13 13:35:28 -0500  172.16.1.4  chein  tty5   198.51.100.141
        stop   task_id=12028  service=exec  port=5   elapsed_time=875
1995-07-13 13:37:04 -0500  172.16.1.4  lol    tty18  198.51.100.129
        stop   task_id=11613  service=exec  port=18  elapsed_time=909
1995-07-13 14:09:02 -0500  172.16.1.4  billw  tty18  198.51.100.152
        start  task_id=17150  service=exec  port=18
1995-07-13 14:09:02 -0500  172.16.1.4  billw  tty18  198.51.100.152
        start  task_id=17150  service=exec  port=18

  access log = "|exec sudo /path/to/tacspooflog-ng.pl 127.0.0.1"

4.2.3.2. User Messages

User messages, e.g. the Username prompt, can be customized, both at device and realm level:

message USERNAME = "utilisateur"

Supported messages and their defaults:

4.2.3.3. Limits and timeouts

A number of global limits and timeouts may be specified at realm and global level:

• connection timeout = s

  Terminate a connection to a NAS after an idle period of at least s seconds.

  Default: 600

• context timeout = s

  Clears context cache entries after s seconds of inactivity. Default: 3600 seconds.

  Default: 3600

  This configuration will be accepted at realm level, too.

• warning period = d

  Set warning period for password expiry to d days.

  Default: 14

• max-rounds = n

  This sets an upper limit on the number of packet exchanges per session. Default: 40, acceptable range is from 1 to 127.

id = spawnd {
    listen { port = 4949 realm = heck }
    listen { port = 4950 realm = heck tls = yes }
    spawn { instances min = 1 instances max = 32 }
    id = tac_plus-ng {
            ...
        realm heck {
            tls cert-file = /somewhere/tac-ca/server.tacacstest.crt
            tls key-file = /somewhere/tac-ca/server.key
            tls ca-file = /somewhere/tac-ca/ca.crt
            ...
        }
    }
}

4.2.3.4. Miscellaneous

In realm context:

• haproxy auto-detect = ( yes | no )

  Enable HAProxy protocol v2 auto-detection. Defaults to no.

In spawnd listen context,

• haproxy = ( yes | no )

  will will tell tac_plus-ng to auto-detect that a connection is proxied via HAProxy protocol 2.

  A suitable HAProxy configuration could look similar to:

  frontend tacplus
      bind *:49
      mode tcp
      default_backend backendtacplus
  
  backend backendtacplus
      balance source
      server tacserver1 127.0.0.1:4949 no-check send-proxy-v2
  

• tls = ( yes | no )

  will tell tac_plus-ng whether the connection is TLS encrypted.

• vrf = ( vrf-name | vrf-number )

  will tell spawnd listen to bind(2) to the requested VRF (vrf-name on Linux, vrf-number on OpenBSD).

Example:

id = spawnd {
    ...
    listen {
        port = 49
        vrf = vrf-blue
        tls = true
        haproxy = true
    }
    ....
}

4.2.3.5. Realm Inheritance

Realms inherit quite some configuration from their parent realm:

4.2.3.6. Railroad Diagrams

4.2.3.7. Networks

Networks consist of IP addresses or other networks. They may overlap. Networks can be used in ACLs. The parent of a network may be set either implicitly (by defining it it parent context) or explicitly.

  net home {
        address = 172.16.0.0/23
        net dev {
            address = 172.16.0.15
        }
        parent = ...

  }

4.2.3.8. Devices (Hosts)

The daemon will talk to known NAS addresses only. Connections from unknown addresses will be rejected.

If you want tac_plus-ng to encrypt its packets (and you almost certainly do want this, as there can be usernames and passwords contained in there), then you'll have to specify an (non-empty) encryption key. The identical key must also be configured on any NAS which communicates with tac_plus.

To specify a global key, use a statement similar to

  device world4 {
    key = "your key here"
    address = 0.0.0.0/0
  }

(where world is not a keyword, but just some arbitrary character string).

Double Quotes

You only need double quotes on the daemon if your key contains spaces. Confusingly, even if your key does contain spaces, you should never use double quotes when you configure the matching key on the NAS. The daemon will reject connections from devices that have no encryption key defined. Double quotes within double-quoted strings may be escaped using the backslash character \ (which can be escaped by itself), e.g.: key = "quo\\te me\"." translates to the ASCII sequence quo\te me".

Any CIDR range within a device definition needs to to be unique, and the most specific definition will match. The requirement for unambiguousness is quite simply based on the fact that certain device object attributes (key, prompt, enable passwords) may only exist once.

If compiled with TLS support, primary criteria for device object selection with TLS is no longer the NAS IP address but the certificate DNS SANs (OpenSSL only), the subject and/or the common name. E.g., CN=server.tacacstest.demo,OU=org,OU=local will check for device objects named CN=server.tacacstest.demo,OU=org,OU=local, OU=org,OU=local, OU=local and then for server.tacacstest.demo, tacacstest.demo and demo before falling back to IP based selection.

On the NAS, you also need to configure the same key. Do this by issuing the current variant of:

aaa new-model
tacacs-server host 192.168.0.1 single-connection key your key here

The optional single-connection parameter specifies that multiple sessions may use the same TCP/IP connection to the server.

Generally, the syntax for device declarations conforms to

device name { key-value pairs }

The key-value pairs permitted in device sections of the configuration file are explained below.

• key [warn] ( YYYY-MM-DD | s ) ] = string

  This sets the key used for encrypting the communication between server and NAS. Multiple keys may be set, making key migration from one key to another pretty easy. If the warn keyword is specified, a warning message is logged when a NAS actually uses the key. Optionally, the warn keyword accepts a date argument that specifies when the warnings should start to appear in the logs.

  During debugging, it may be convenient to temporarily switch off encryption by using an empty key:

  key = ""

  Be careful to remember to switch encryption back on again after you've finished debugging.

• address = cidr

  Adds the address range specified by cidr to the current device definition.

  

  Railroad diagram: CIDR

• address file = file

  Add the addresses from file to the current device definition. Shell wildcard patterns are expanded by glob(3).

• single-connection ( may-close ) = ( yes | no )

  This directive may be used to permit or deny the single-connection feature for a particular device object. The may-close keyword tells the daemon to close the connection if it's unused.

  	Caveat Emptor
  	There's a slight chance that single-connection doesn't work as expected. The single-connection implementation in your router or even the one implemented in this daemon (or possibly both) may be buggy. If you're noticing weird AAA behaviour that can't be explained otherwise, then try disabling single-connection on the router.

  This configuration will be accepted at realm level, too.

• parent = deviceName

  This sets the the parent devices. Definitions not found in the current device will be looked up there, recursively.

• device deviceName { DeviceAttr }

  Devices can be defined in device context, too.

• script { tacAction }

  Scripts can be used in device context. These are run before AAA and mey be used to permit or deny access, or to rewrite usernames.

  This configuration will be accepted at realm level (for the default host, too.

  device ... {
    ...
    welcome banner = "Welcome. Today is %A.\n"
    ...
  }

  device ... {
    ...
    bug compatibility = 2
    ...
  }

device = customer1 {
    address = 10.0.0.0/8
    key = "your key here"
    welcome banner = "\nHitherto shalt thou come, but no further. (Job 38.11)\n\n"
    enable 15 = clear whatever
}

device = test123 {
    address = 10.1.2.0/28
    address = 10.12.1.30/28
    address = 10.1.1.2
    # key/banners/enable will be inherited from 10.0.0.0/8 by default,
    # unless you specify "inherit = no"
    address file = /some/path/test123.cidr
    welcome banner = "\nGo away.\n\n"
}

4.2.3.9. Time Ranges

timespec objects may be used for time based profile assignments. Both cron and Taylor-UUCP syntax are supported; see you local crontab(5) and/or UUCP man pages for details. Syntax:

timespec = timespec_name { "entry" [ ... ] }

Example:

# Working hours are from Mo-Fr from 9 to 16:59, and
# on Saturdays from 9 to 12:59:
timespec workinghours {
    "* 9-16 * * 1-5"   # or: "* 9-16 * * Mon-Fri"
    "* 9-12 * * 6"     # or: "* 9-12 * * Sat"
}

timespec sunday { "* * * * 0" }

timespec example {
    Wk2305-0855,Sa,Su2305-1655
    Wk0905-2255,Su1705-2255
    Any
}

4.2.3.10. Access Control Lists

Access Control Lists (or, more exactly, Access Control Scripts) are the main component of ruleset evaluation.

Scripts may currently be used for ACLs, in host and profile declaration scope and in rule sets. If a script in a hierarchy doesn't return a final verdict (these are permit and deny), other scripts in the hierarchy may be evaluated. Default evaluation order is

script-order host = bottom-up
script-order realm = bottom-up
script-order profile = bottom-up

but you may prefer to change that to top-down to have parent scripts executed first.

To provide an example for that: In

profile A {
    script { ... }
    profile B {
        script { ... }
    }

the script part from A will by default (bottom-up be evaluated, if the B script result isn't final.

In contrast, for

script-order profile = top-down
profile A {
    script { ... }
    profile B {
        script { ... }
    }

the A part takes precedence and the B script will one be evaluated if the A result isn't final.

skip parent-script = yes may be used (at profile, host and realm level) to ignore scripts defined at a higher hierarchy level.

Scripting examples:

• acl acl_name { tac_action ... }

  Example:

      acl myacl123 {
          if (nas == 1.2.3.4 || nac = SomeHostName || nac-dns =~ /\\.example\\.com$/) deny
      }

• script = { tac_action ... }

  Example:

      profile tunnelAdmin {
          script {
              if (service == shell) {
                  if (cmd == "") permit # required for shell startup
                  if (cmd =~ /^(no\s)?shutdown\s/) permit
                  if (cmd =~ /^interface Tunnel/) permit
                  deny
              }
          }
      }
  
      user joe {
          password = ...
          member = ops
      }
      ruleset {
          rule opsRule {
              script {
                  if (group == ops)
                      profile = tunnelAdmin
                      permit
              }
          }
      }

4.2.3.11. Rewriting User Names

A script may refer to a rewrite profile defined at realm level to rewrite user names. For example, the following will map both admin and root to jane.doe, and convert all other usernames to lower-case:

rewrite rewriteRule {
    rewrite /^admin$/ jane.doe
    rewrite /^root$/ jane.doe
    rewrite /^.*$/ \L$0
}

device ... {
    ...
    script { rewrite user = rewriteRule }
    ...
}

You can limit the usage of a rewritten-to user with the rewritten-only directive, e.g.:

    rewrite rewriteRule {
        rewrite /^.*$/ nopassword
    }
    user nopassword {
        password login = permit
        password pap = login
        member = ...
        rewritten-only
    }

4.2.3.12. Users

The basic form of a user declarations is

user username { ...  }

A user or group declaration may contain key-value pairs and service declarations.

The following declarations are valid in user context only:

• password login = ( ( clear | crypt ) password | mavis | permit | deny )

  The login password authenticates shell log-ins to the server.

  password login = crypt aFtFBT4e5muQE
  password login = clear Ci5c0

  For the argument after crypt you may use whatever hashes your crypt(3) implementation supports.

  If the mavis keyword is used instead, the password will be looked up via the MAVIS back-end. It will not be cached. This functionality may be useful if you want to authenticate at external systems, despite static user declarations in the configuration file.

• password pap = ( ( clear | crypt ) password | login|mavis | permit | deny )

  The pap authenticates PAP log-ins to the server. Just like with login, the password doesn't need to be in clear text, but may be hashed, or may be looked up via the MAVIS back-end. You can even map pap to login globally by configuring password pap = login in realm context.

• password chap = ( clear password | permit | deny )

  For CHAP authentication, a cleartext password is required.

• password ms-chap = ( clear password | permit | deny )

  For MS-CHAP authentication, a cleartext password is required.

• password { ... }

  This directive allows for nested specification of passwords. Example:

  user marc {
      password {
          login = clear myLoginPassword
          pap = clear myPapPassword
      }
  }

• enable [ level ] = ( permit | deny | login | ( clear | crypt ) password )

  This directive may be used to set user specific enable passwords, to use the login password, or to permit (without password) or refuse any enable attempt. Enable secrets defined at user level have precedence over those defined at device level. level defaults to 15.

  The default privilege level for an ordinary user on the NAS is usually 1. When a user enables, she can reset this level to a value between 0 and 15 by using the NAS enable command. If she doesn't specify a level, the default level she enables to is 15.

• message = string

  A message displayed to the user upon log-in.

• hushlogin = ( yes | no )

  Setting hushlogin to yes keeps the daemon from displaying motd and user messages upon login.

• valid from = ( YYYY-MM-DD | s )

  The user profile will be valid starting at the given date, which can be specified either in ISO8601 date format or as in seconds since January 1, 1970, UTC.

• valid until = ( YYYY-MM-DD | s )

  The user profile will be invalid after the given date.

• member = groupOne[,groupTwo]*

  This specifies group membership. A user can be a member of multiple groups and groups can be members of a parent group.

4.2.3.13. Groups

A user can be a member of multiple groups. A user that is a member of a group that comes with a parent group is a member of the latter, too. Group are defined using

group groupname {  ...  }

The following key-value pairs are valid for groups:

• member = groupOne[,groupTwo]*

  This specifies group membership.

• parent = groupName

  The parent of a group can be set explicitly.

• group groupName { GroupAttr }

  Groups may be parents of other groups.

4.2.3.14. Profiles

Profiles are collections of services that can be assigned to users via the policy rule-set. Syntax is

profile profileName { profileAttr }

Profiles are collections of services available to a user. A couple of configuration attributes are service specific and only valid in certain contexts:

SHELL (EXEC) Service

Shell startup should have an appropriate script definition

script {
if (service == "shell" && cmd == "")
    permit
}

defined. Valid configuration directive within the curly brackets are:

• script { tacAction }

  Commands can be permitted or denied using script syntax:

  script {
      if (service == "shell" && cmd == "")
          permit
      if (cmd =~ /^write term/) deny
      if (cmd =~ /^configure /) deny
      permit
  }

• profile SubProfileName { ... }

  This defines a new profile that inherits most values from its parent profile.

• parent = ParentProfileName

  This sets ParentProfileName as parent profile. Parent profiles defined in parent realms are accepted, too.

Have a look at the authorization log in case you're unsure what commands and arguments the router actually sends for verification. E.g.,

Non-Shell Services

E.g. for PPP, protocol definitions may be used:

script {
    if (service == "ppp" && protocol == "ip") {
        set addr = 1.1.3.4
        permit
    }
}

The historical

default protocol = permit

will no longer be recognized but can be replaced with a simple

script {
    permit
}

For a Juniper Networks-specific authorization service, use:

script {
    if (service == junos-exec) {
        set local-user-name = NOC
        # see the Junos documentation for more attributes
    }
}

Likewise, for Raritan Dominion SX IP Console Servers:

script {
    if (service == dominionsx) {
        set port-list = "1 3 4 15"
        set user-type = administator # or operator, or observer
    }
}

	Quotes
	If your router expects double-quoted values (e.g. Cisco Nexus devices do), you can advise the parser to automatically add these: set shell:roles = "\"network-admin\"" and set shell:roles = '"network-admin"' } are equivalent, but the latter is more readable.

4.2.3.15. Railroad Diagrams

4.2.3.16. Configuring Non-local Users via MAVIS

MAVIS configuration is optional. You don't need it if you're content with user configuration in the main configuration file.

MAVIS back-ends may dynamically create user entries, based, e.g., on LDAP information.

For PAP and LOGIN,

pap backend = mavis
login backend = mavis

in the global section delegate authentiation to the MAVIS sub-system. Statically defined users are still valid, and have a higher precedence.

By default, MAVIS user data will be cached for 120 seconds. You may change that period using

cache timeout = seconds

in the global configuration section.

4.2.3.17. Configuring Local Users for MAVIS authentication

Under certain circumstances you may wish to keep the user definitions in the plain text configuration file, but authenticate against some external system nevertheless, e.g. LDAP or RADIUS. To do so, just specify one of

    login = mavis
    pap = mavis
    password = mavis

in the corresponding user definition.

4.2.3.18. Configuring User Authentication

User Authentication can be specified separately for PAP, CHAP, and normal logins. CHAP and global user authentication must be given in clear text.

The following assigns the user mary five different passwords for inbound and outbound CHAP, inbound PAP, outbound PAP, and normal login respectively:

user mary {
    password chap = clear "chap password"
    password pap  = clear "inbound pap password"
    password login = crypt XQj4892fjk
}

If

user backend = mavis

is configured in the global section, users not found in the configuration file will be looked up by the MAVIS back-end. You should consider using this option in conjuction with the more sophisticated back-ends (LDAP and ActiveDirectory, in particular), or whenever you're not willing to duplicate your pre-existing database user data to the configuration file. For users looked up by the MAVIS back-end,

pap backend = mavis

and/or

login backend = mavis

(again, in the global section of the configuration file) will cause PAP and/or Login authentication to be performed by the MAVIS back-end (e.g. by performing an LDAP bind), ignoring any corresponding password definitions in the users' profile.

If you just want the users defined in your configuration file to authenticate using the MAVIS back-end, simply set the corresponding PAP or Login password field to mavis (there's no need to add the user backend = mavis directive in this case):

user mary { login = mavis }

4.2.3.19. Configuring Expiry Dates

An entry of the form:

user lol {
    valid until = YYYY-MM-DD
    password login = clear "bite me"
}

will cause the user profile to become invalid, starting after the valid until date. Valid date formats are both ISO8601 and the absolute number of seconds since 1970-01-01.

A expiry warning message is sent to the user when she logs in, by default starting at 14 days before the expiration date, but configurable via the warning period directive.

Complementary to profile expiry,

    valid from = YYYY-MM-DD

activates a profile at the given date.

4.2.3.20. Configuring Authentication on the NAS

On the NAS, to configure login authentication, try

aaa new-model
aaa authentication login default group tacacs+ local

(Alternatively, you can try a named authentication list instead of default. Please see the IOS documentation for details.)

Don't lock yourself out.

As soon as you issue this command, you will no longer be able to create new logins to your NAS without a functioning TACACS+ daemon appropriately configured with usernames and password, so make sure you have this ready. As a safety measure while setting up, you should configure an enable secret and make it the last resort authentication method, so if your TACACS+ daemon fails to respond you will be able to use the NAS enable password to login. To do this, configure: aaa authentication login default group tacacs+ enable or, to if you have local accounts: aaa authentication login default group tacacs+ local If all else fails, and you find yourself locked out of the NAS due to a configuration problem, the section on recovering from lost passwords on Cisco's CCO web page will help you dig your way out.

4.2.3.21. Configuring Authorization

Authorization must be configured on both the NAS and the daemon to operate correctly. By default, the NAS will allow everything until you configure it to make authorization requests to the daemon.

On the daemon, the opposite is true: The daemon will, by default, deny authorization of anything that isn't explicitly permitted.

Authorization allows the daemon to deny commands and services outright, or to modify commands and services on a per-user basis. Authorization on the daemon is divided into two separate parts: commands and services.

4.2.3.22. Authorizing Commands

Exec commands are those commands which are typed at a NAS exec prompt. When authorization is requested by the NAS, the entire command is sent to the tac_plus daemon for authorization.

Command authorization is configured by telling the ruleset to apply a profile to the user. See the Profile section for details.

4.2.3.23. The Authorization Process

Authorizing a single session can result in multiple requests being sent to the daemon. For example, in order to authorize a dialin PPP user for IP, the following authorization requests will be made from the NAS:

1. An initial authorization request to startup PPP from the exec, using the AV pairs service=ppp, protocol=ip, will be made (Note: this initial request will be omitted if you are autoselecting PPP, since you won't know the username yet).

   This request is really done to find the address for dumb PPP (or SLIP) clients who can't do address negotiation. Instead, they expect you to tell them what address to use before PPP starts up, via a text message e.g. "Entering PPP. Your address is 1.2.3.4". They rely on parsing this address from the message to know their address.

2. Next, an authorization request is made from the PPP subsystem to see if PPP's LCP layer is authorized. LCP parameters can be set at this time (e.g. callback). This request contains the AV pairs service=ppp, protocol=lcp.

3. Next an authorization request to startup PPP's IPCP layer is made using the AV pairs service=ppp, protocol=ipcp. Any parameters returned by the daemon are cached.

4. Next, during PPP's address negotiation phase, each time the remote peer requests a specific address, if that address isn't in the cache obtained in step 3, a new authorization request is made to see if the peers requested address is allowable. This step can be repeated multiple times until both sides agree on the remote peer's address or until the NAS (or client) decide they're never going to agree and they shut down PPP instead.

4.2.3.24. Authorization Relies on Authentication

Since we pretty much rely on having a username in authorization requests to decide which addresses etc. to hand out, it is important to know where the username for a PPP user comes from. There are generally 2 possible sources:

1. You force the user to authenticate by making her login to the exec and you use that login name in authorization requests. This username isn't propagated to PPP by default. To have this happen, you generally need to configure the if-needed method, e.g.

   aaa authentication login default tacacs+
   aaa authentication ppp default if-needed

2. Alternatively, you can run an authentication protocol, PAP or CHAP (CHAP is much preferred), to identify the user. You don't need an explicit login step if you do this (so it's the only possibility if you are using autoselect). This authentication gets done before you see the first LCP authorization request of course. Typically you configure this by doing:

   aaa authentication ppp default tacacs+ 
   int async 1
     ppp authentication chap

If you omit either of these authentication schemes, you will start to see authorization requests in which the username is missing.

4.2.3.25. Configuring Service Authorization

A list of AV pairs is placed in the daemon's configuration file in order to authorize services. The daemon compares each NAS AV pair to its configured AV pairs and either allows or denies the service. If the service is allowed, the daemon may add, change or delete AV pairs before returning them to the NAS, thereby restricting what the user is permitted to do.

4.3.1.1. LDAP Custom Schema Backend

For LDAP_SERVER_TYPE set to tacacs_schema, the program expects the LDAP server to support the experimental ldap.schema, included for OpenLDAP and Fedora-DS. The schema files are located in the mavis/perl directory.

The new schema allows for a auxiliary object class

objectClass: tacacsAccount

which introduces a couple of new attributes. A sample user entry could then look similar to the following LDIF snippet:

dn: uid=marc,ou=people,dc=example,dc=com
uid: marc
cn: Marc Huber
objectClass: posixAccount
objectClass: inetOrgPerson
objectClass: shadowAccount
objectClass: tacacsAccount
shadowMax: 10000
uidNumber: 1000
gecos: Marc Huber
givenName: Marc
sn: Huber
gidNumber: 500
shadowLastChange: 14012
loginShell: /bin/bash
homeDirectory: /Users/marc
mail: marc@example.com
userPassword:: abcdefghijklmnopqrstuvwxyz=
tacacsClient: 192.168.0.0/24
tacacsClient: management
tacacsMember: readonly,readwrite
tacacsProfile: { valid until = 2010-01-30 chap = clear ahzoi5Ue }

As tacacsProfile may (and most probably will) contain sensitive data, you should consider setting up LDAP ACLs to restrict access.

You should be pretty familiar with OpenLDAP (or, for that matter, Fedora-DS) if you're willing to go this route. For current versions of OpenLDAP: Use ldapadd to add tacacs_schema.ldif to the cn=config tree. For older versions, add tacacs.schema to the list of included schema and objectClass definitions in slapd.conf.

4.3.1.2. Active Directory Backend

If LDAP_SERVER_TYPE is set to microsoft, the script back-ends to AD servers. Sample configuration (you'll find that one in the extra directory, too):

#!/usr/local/sbin/tac_plus-ng
id = spawnd {
        listen = { port = 49 }
        spawn = {
                instances min = 1
                instances max = 10
        }
        background = yes
}

id = tac_plus-ng {
        # access log = /var/log/tac_plus-ng/access/%Y%m%d.log
        # accounting log = /var/log/tac_plus-ng/acct/%Y%m%d.log

        mavis module = groups {
                groups filter = /^(admins|guest|readonly)$/ # these are defined below
                memberof filter = /^CN=tacacs_/ # use this as a prefix
        }


        mavis module = external {
                setenv LDAP_SERVER_TYPE = "microsoft"
                setenv LDAP_HOSTS = "172.16.0.10:389"
                setenv LDAP_BASE = "dc=example,dc=local"
                setenv LDAP_USER = "tacacs@example.local"
                setenv LDAP_PASSWD = "password"
                setenv TACACS_GROUP_PREFIX = "tacacs_"
                setenv UNLIMIT_AD_GROUP_MEMBERSHIP = 1
                #setenv REQUIRE_TACACS_GROUP_PREFIX = 1
                exec = /usr/local/lib/mavis/mavis_tacplus_ldap.pl
        }

        login backend = mavis
        user backend = mavis
        pap backend = mavis

        device world {
                address = ::/0
                welcome banner = "Welcome\n"
                enable 15 = clear secret
                key = demo
        }

        profile admins {
                script {
                        if (service == shell) {
                                if (cmd == "")
                                        set priv-lvl = 15
                                permit
                        }
                }
        }

        profile guest {
                enable = deny
                script {
                        if (service == shell) {
                                if (cmd == "")
                                        set priv-lvl = 1
                                permit
                        }
                }
        }

        group admins
        group guest

        user demo {
                password login = clear demo
                member = admins
        }

        user = readonly {
                password login = clear readonly
                member = guest
        }
        ruleset {
                rule {
                        script { 
                                if (memberof =~ /^CN=tacacs_admins,/) { profile = admins permit }
                                if (memberof =~ /^CN=tacacs_readonly,/) { profile = readonly permit }
                        }
                }
                rule {
                        script { 
                                if (member == guest) { profile = guest permit }
                        }
                }
        }
}

4.3.1.3. Generic LDAP Backend

If LDAP_SERVER_TYPE is set to generic, the script won't require any modification to your LDAP server, but only authenticates users (with login = mavis, pap = mavis or password = mavis declaration) defined in the configuration file. No authorization is done by this back-end.

4.3.5.1. Sample Configuration

## Use tacinfo_cache to cache authorization data to disk:
mavis module = tacinfo_cache {
    directory = /tmp/tacinfo
}

## You can use either the Perl module ...
#mavis module = external {
#   exec = /usr/local/lib/mavis_tacplus_radius.pl
#   setenv RADIUS_HOST = 1.2.3.4:1812 # could add more devices here, comma-separated
#   setenv RADIUS_SECRET = "mysecret"
#   setenv RADIUS_GROUP_ATTR = Class
#   setenv RADIUS_PASSWORD_ATTR = Password # defaults to: User-Password
# }
## ... or the freeradius-client based code:
mavis module = external {
    exec = /usr/local/sbin/radmavis "radmavis" "group_attribute=Class" "authserver=1.2.3.4:1812:mysecret"
}