1 TAC_PLUS Developer's Kit vF4.0.2.alpha
2 --------------------------------------
6 Note: this is a DEVELOPER'S KIT. You probably shouldn't be using this
7 if you don't need source code. Instead, consider using CiscoSecure,
8 Cisco's supported, commercial Tacacs+ daemon.
10 Copyright (c) 1995-1998 by Cisco systems, Inc.
12 Permission to use, copy, modify, and distribute this software for
13 any purpose and without fee is hereby granted, provided that this
14 copyright and permission notice appear on all copies of the
15 software and supporting documentation, the name of Cisco Systems,
16 Inc. not be used in advertising or publicity pertaining to
17 distribution of the program without specific prior permission, and
18 notice be given in supporting documentation that modification,
19 copying and distribution is by permission of Cisco Systems, Inc.
21 Cisco Systems, Inc. makes no representations about the suitability
22 of this software for any purpose. THIS SOFTWARE IS PROVIDED ``AS
23 IS'' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING,
24 WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
25 FITNESS FOR A PARTICULAR PURPOSE.
27 Please NOTE: None of the TACACS code available here comes with any
28 warranty or support, however, comments or questions may be addressed
29 to Cisco systems via email at the address:
31 customer-service@cisco.com (or more simply)
34 and we will do our best to handle them, though we cannot guarantee a
35 timely response, as this code is UNSUPPORTED. Be sure you've read this
36 user's guide, including the frequently asked questions include in it,
39 Cisco systems also maintains an extensive World Wide Web site at
43 In addition, there are two mailing lists which may be of interest to
46 The first is a mailing list run by spot.Colorado.EDU which discusses
47 many things pertaining to Cisco products. It is not run by Cisco
48 Systems, Inc. and is not part of Cisco's formal service request
49 channels, however, many knowledgeable people, including staff members
50 of Cisco Systems, Inc. voluntarily read and respond on the list.
52 Requests to be added to or deleted from the list at spot.Colorado.EDU,
53 along with other administrative issues concerning it can be sent to:
55 cisco-request@spot.Colorado.EDU
57 There is also a relatively new list called TACPLUS-L, run by
58 disaster.com, created for the purpose of information exchange between
59 TACACS+ Users. It is intended as a supplement to the list at
60 spot.Colorado.EDU, aiding TACACS+ users and prospective users in many
61 issues including but not limited to technical support, bug reports and
62 workarounds, configuration information, recommendations for future
63 versions of TACACS+, and general talk about TACACS+ development,
64 implementation, administration, etc.
66 Please note that neither of these lists is in fact connected with
67 Cisco Systems, Inc. or any of its subsidiaries. Standard etiquette
70 To subscribe to the TACPLUS-L list, send a message to
72 tacplus-l-request@disaster.com
74 In the body of the letter, enter
76 SUBSCRIBE TACPLUS-L your Name
78 to be automatically added, or visit their web page at
79 http://www.disaster.com/tacplus/.
81 Also, Robert Kiessling maintains a TACACS+ FAQ at
82 http://www.easynet.de/tacacs-faq.
84 Lastly, I am always interested in seeing contributed patches, so
85 consider mailing any modifications you make, as context diffs (be sure
86 to indicate with the version your patches are based on), to
87 tacacs-patches@cisco.com. As always, no support is implied, nor any
88 assurance that patches will be made available via ftp (though that is
89 my intent) or incorporated into any code.
94 NAS --- A Network Access Server e.g. a Cisco box, or any other
95 *client* which makes tacacs+ authentication and authorization
96 requests, or generates Tacacs+ accounting packets.
98 Daemon -- A program which services network requests for authentication
99 and authorization, verifies identities, grants or denies
100 authorizations, and logs accounting records.
102 passwd(5) files -- files conforming to Unix password style format, as
103 documented in section 5 of the Unix manuals.
105 AV pairs -- strings of text in the form "attribute=value" sent between a
106 NAS and a tacacs+ daemon as part of the Tacacs+ protocol.
108 Since a NAS is sometimes referred to as a server, and a daemon is also
109 often referred to as a server, the term "server" has been avoided here
110 in favor of the less ambiguous terms "NAS" and "Daemon".
112 TACACS, XTACACS and TACACS+
113 ---------------------------
115 Note that there are now at least 3 versions of authentication protocol
116 that people commonly refer to as "TACACS".
118 The first is ordinary tacacs, which was the first one offered on Cisco
119 boxes and has been in use for many years. The second is an extension
120 to the first, commonly called Extended Tacacs or XTACACS, introduced
123 The third one is TACACS+ (or T+ or tac_plus) which is what is documented
124 here. TACACS+ is NOT COMPATIBLE with any previous versions of tacacs.
126 In addition to the 3 versions of tacacs running on Cisco boxes, the
127 fact that we distribute the source code to the daemon has meant that
128 additional implementations of tacacs daemons have been produced by
129 people who have made modifications to our source code.
133 Tac_plus is known to build and run on the following platforms:
135 AIXv3.2 (using -DAIX and bsdcc. See tac_plus.h for more details).
136 HP/UX A.09.01 using -DHPUX
137 i86 Solaris 2.4 (SUNOS 5.4), using SUNpro SW2.0.1 & -DSOLARIS
138 Sun4 Solaris 2.4 using SUNpro SC3.0.1 and -DSOLARIS
141 MIPS R3K SGI IRIX 4.05F (using -DMIPS)
142 BSDI BSD/386 1.1 (using -DBSDI)
143 FREEBSD 2.0-RELEASE (using -DFREEBSD)
144 LINUX 1.2.8 (using -DLINUX)
146 To build tac_plus, untar the tarfile distribution into a clean
149 tar -xvf tac_plus.tar
151 Edit the top of the Makefile to select the appropriate defaults
152 for your system. Then type
156 The default version can authenticate using its internal database,
157 s/key or passwd(5) style files. Authorization is done via the
158 internal database or via calls to external programs, which the
159 administrator configures.
161 To use S/KEY, you must obtain and build the s/key library (libskey.a)
162 yourself. You can then compile in S/KEY support per the instructions
163 for S/KEY in the Makefile. I got my S/KEY code originally from
164 crimelab.com but now it appears the only source is ftp.bellcore.com. I
165 suggest you try a web search for s/key source code.
167 Note: S/KEY is a trademark of Bell Communications Research (Bellcore).
169 Should you need them, there are routines for accessing password files
170 (getpwnam,setpwent,endpwent,setpwfile) in pw.c.
172 Lastly, you may also need to add lines to your /etc/services file to
173 get tacacs+ to work correctly e.g. something along the lines of:
177 You'll need to consult your system manuals for exact details of how to
180 A NOTE ABOUT ARAP, MSCHAP AND DES
181 ---------------------------------
182 If you have access to a DES library which implements the calls:
189 then you can define DES in tac_plus.h and link tac_plus with your DES
190 library. This is recommended, as it will allow you to process ARAP and MSCHAP
191 requests on your daemon, which is more efficient, and also more secure
192 than processing them on the NAS.
194 If you don't have access to des (which is U.S. export controlled), you
195 can simply leave DES undefined in tac_plus.h. ARAP and MSCHAP
196 authentication will still work, but it will be slightly less
197 efficient, since the NAS will attempt to get the daemon to do the DES
198 calculation before falling back to the alternative of calculating DES
199 on the NAS. It's also slightly less secure, because if someone
200 discovers your encryption key, they can then download ARAP and MSCHAP
201 secrets from your daemon.
203 Note that this issue arises solely because U.S. government regulations
204 currently make it difficult to export the source code for DES outside
205 the US and Canada, which is why it is not included in this
208 Lastly, this limitation of MSCHAP, ARAP and DES has no bearing on the
209 use of des passwords for regular logins. Regular logins also use DES
210 but they do it via the "crypt" system call, which is usually found in
211 a library on the Unix host where you compile your daemon.
213 There are additional restrictions on doing MSCHAP (see the FAQ later
217 ---------------------
219 Tac_plus is configured via a single configuration file. You can create
220 a configuration file from scratch or, if you have passwd(5) and
221 supplementary files from earlier versions of tacacs, you can convert
222 these to configuration file format by running the supplied perl script
225 CONVERTING EXISTING PASSWD(5) FILES
226 -----------------------------------
228 To convert an existing passwd(5) file e.g. one used with an older
229 version of tacacs, use the convert.pl perl script as follows:
231 convert.pl <passwd file> [-g] [<supplementary file>]
233 1). If you have no supplementary file, simply omit it.
235 2). If the groupid field of your passwd file does NOT represent a
236 valid acl number (e.g if it's really a unix passwd file this field is
237 a group id, not an acl number), just omit the -g flag.
239 The rest of this document assumes that you are configuring tac_plus
242 CONFIGURING TAC_PLUS FROM SCRATCH
243 ---------------------------------
245 A configuration file consists of some top-level directives for setting
246 defaults and for setting up the encryption key, followed by a
247 declaration for each user and group you want to configure. Within
248 each user or group declaration, there are declarations for
249 authenticating and authorizing that user.
251 1). Configuring the encryption key
253 If you want tac_plus to encrypt its packets (and you almost certainly
254 *DO* want this, as there can be usernames and passwords contained in
255 these packets), then you must specify an encryption key in the
256 configuration file. The identical key must also be configured on any
257 NAS which communicates with tac_plus.
259 This is done using the statement
261 key = "your key here"
263 NOTE: You only need double quotes on the daemon if your key contains
266 Confusingly, even if your key does contain spaces, you should NEVER
267 use double quotes when you configure the matching key on the NAS.
269 During debugging, it may be convenient to temporarily switch off
270 encryption by not specifying any key. Be careful to remember to
271 switch encryption back on again after you've finished debugging.
273 The current code does not support host-specific keys (left as an
274 exercise to the reader).
276 On the NAS, you also need to configure the *same* key. Do this by
280 tacacs-server key <your key here>
282 COMMENTS IN CONFIGURATION FILES
283 -------------------------------
284 Comments can appear anywhere in the configuration file, starting with
285 the # character and extending to the end of the current line. Should
286 you need to disable this special meaning of the # character, e.g. if
287 you have a password containing a # character, simply enclose the string
288 containing it within double quotes.
290 CONFIGURING USERS AND GROUPS
291 ----------------------------
293 Each user may belong to a group (but only one group). Each group may
294 in turn belong to one other group and so on ad infinitum.
296 Users and groups are declared as follows. Here we declare two users
297 "fred" and "lily", and two groups, "admin" and "staff".
299 Fred is a member of group "admin", and group "admin" is in turn a
300 member of group "staff". Lily is not a member of any group.
303 # user lily is not a member of any group
304 # and has nothing else configured as yet
308 # fred is a member of group admin
313 # group admin is a member of group staff
318 # group staff is not a member of any group
324 In general, when the daemon looks up values e.g. passwords, it will
325 look first to see if the user has her own password. If not, it looks
326 to see if she belongs to a group and if so, whether the group has a
327 password defined. If not, this process continues through the hierarchy
328 of groups (a group can be a member of another group) until a value is
329 found, or there are no more groups.
331 This recursive process occurs for lookups of expiration dates, for
332 pap, arap and chap "secrets", and also for authorization parameters (see
335 A typical configuration technique is thus to place users into groups
336 and specify as many groupwide characteristics in the group declaration
337 as possible. Then, individual user declarations can be used to
338 override the group settings for selected users as needed.
340 MEMBERSHIP IN MULTIPLE GROUPS
341 -----------------------------
343 Besides the descibed single-membership of user to some group, you may also find
344 useful if user (or host) belongs to multiple groups at once. You can naturally
345 specify multiple "member = group_X" commands for such user:
348 # fred is a member of both groups: admins_company_A, admins_company_B
349 member = admins_company_A
350 member = admins_company_B
353 group = admins_company_A {
354 # group admins_company_A is not a member of any group
355 member = admins_company_A_privilege_X
356 member = admins_company_A_privilege_Y
358 group = admins_company_A_privilege_X {
360 group = admins_company_A_privilege_Y {
363 group = admins_company_B {
364 # group admins_company_B is not a member of any group
367 Here it is important to respect the ordering of "member" commands: Any
368 searching for attributes/values is done by Depth-First Search - so Daemon would
369 first try to look all members of admins_company_A and THEN (after it would
370 failed to find any) it would start to searching through admins_company_B. The
371 searching through the proposed example would be done in the following order:
375 admins_company_A_privilege_X
376 admins_company_A_privilege_Y
379 Sometimes you would want to only list some members (users, hosts or groups) but
380 you don't want to specify any attributes for them. You would be able to do it:
382 group = city_X_NASes {
384 host first.NAS.X.city {
385 member = city_X_NASes
387 host second.NAS.X.city {
388 member = city_X_NASes
391 But you will probably find more comfortable to use "enlist" keyword. It has
392 the same functionality but it goes from the other way:
394 member: current entity is connected as CHILD to the specified PARENT entity
395 enlist: specified entity is connected as CHILD to the current one as PARENT
397 The example would be re-written using "enlist" keyword as:
399 group = city_X_NASes {
400 enlist = host first.NAS.X.city
401 enlist = host second.NAS.X.city
404 As you can see, "enlist" doesn't require the existence of the given entity as
405 it would loose its primary purpose. If the entity doesn't exist it will be
406 automatically created (as empty one) - this doesn't apply to "member"! Any
407 argument to "member" MUST already exist. "enlist" is provided to save you from
408 writing a lot of empty definition lines like:
410 host = first.NAS.X.city {
413 All forward references are not a problem, you can still make membership or
414 enlistment on the top of the file with the entity which will be defined on the
415 end of the configuration file.
417 CONFIGURING USER AUTHENTICATION
418 -------------------------------
420 User Authentication can be specified separately for PAP, ARAP, CHAP,
421 and normal logins. In addition, a user global authentication method
422 can be given that will be used if a per-protocol method is not
425 PAP, ARAP, CHAP, and global user authentication must be given in clear
428 The following assigns the user mary five different passwords for ARAP,
429 inbound and outbound CHAP, inbound PAP, outbound PAP, and normal login
433 arap = cleartext "arap password"
434 chap = cleartext "chap password"
435 pap = cleartext "inbound pap password"
436 opap = cleartext "outbound pap password"
437 login = des XQj4892fjk
441 The following assigns the user agnes a single password for all the
442 above types of login (except outbound PAP):
445 global = cleartext "Agnes global password"
448 NOTE: you cannot use a global user password for outbound PAP. This is
449 because outbound PAP is implemented by sending the password from the
450 daemon to the NAS. This is a security issue if the TACACS+ key is ever
453 There are 3 ways to authenticate a user for login.
455 1). You can include a DES (or cleartext) password for a user or for a
456 group that s/he is a member of, viz:
460 # this is lily's encrypted DES password. It overrides the admin
462 login = des XQkR21zMB0TDU
466 # fred is a member of group admin. He inherits the group's password
467 # as he does not have his one of his own.
472 # group admin has a cleartext password which all members share
473 # unless they have their own password defined
474 login = cleartext foobar
477 If no password is needed for this user, this can be accomplished with
478 the 'nopassword' option:
484 NOTE: The C program built from generate_passwd.c may be used to
485 hand-generate encrypted passwords, or they may be taken from a Unix
486 passwd (or shadow) file.
488 2). Authentication using passwd(5) files.
490 For selected users, you can perform DES authentication using existing
491 passwd(5) files instead of entering the password into the
492 configuration file directly (though using passwd(5) files is
493 noticeably less efficient for large files).
495 You can specify this behavior per-user, by naming a passwd(5) file in
496 the password declaration (instead of giving a DES password), as
500 # look in file /etc/tac_plus_passwords to authenticate this user
501 login = file /etc/tac_plus_passwords
504 3). Authentication using s/key.
506 If you have successfully built and linked in a suitable s/key library
507 and compiled tac_plus to use s/key, you can then specify that a user
508 be authenticated via s/key, as follows:
514 RECURSIVE PASSWORD LOOKUPS
515 ---------------------------
517 As stated earlier, authentication passwords are looked up recursively:
518 The daemon looks first to see if the user has her own password. If
519 not, it looks to see if she belongs to a group which has a
520 password. This process recurses through the hierarchy of groups (a
521 group can be a member of another group) until a password is found, or
522 there are no more groups.
524 CONFIGURING DEFAULT AUTHENTICATION
525 -----------------------------------
526 By default, an unrecognized user will be denied authentication (NOTE:
527 there is no way to authenticate someone with no username).
529 At the top level of the configuration file, you can set the default
530 authentication to use a passwd(5) file, viz:
532 default authentication = file /etc/passwd
534 The effect of this statement is that if a user does not appear in the
535 configuration file, the daemon will attempt to authenticate the user
536 using passwords from this file i.e. /etc/passwd in this example.
538 If you have passwd(5) files from previous versions of tacacs daemons,
539 this facility allows you to authenticate using the passwd(5) from
540 older versions of tacacs, while you migrate to using the new
543 CONFIGURING EXPIRY DATES
544 ------------------------
545 An entry of the form:
548 expires = "MMM DD YYYY"
549 password = cleartext "bite me"
552 will cause the user's passwords to become invalid, starting on the
553 expiry date. The only valid date format is e.g. "Jan 1 1980". Case is
556 A expiry warning message is sent to the user when she logs in,
557 starting at 14 days before the expiration date.
559 On expiry, the administrator must re-set the expiry date in the
560 configuration file in order to grant continued access. Expiry applies
561 to all password types except "file" passwords.
563 If passwd(5) files are being used for authentication, the "expires"
564 field in the configuration file is not consulted. Instead, the daemon
565 looks at the the "shell" field of the password file entry for a valid
568 If Solaris shadow password files are used for authentication, the
569 "expires" field in the configuration file is not consulted. The expiry
570 field from the shadow password file (if it exists) is used as the
573 CONFIGURING AUTHENTICATION ON THE NAS
574 -------------------------------------
576 On the NAS, to configure login authentication on all lines (including
577 vty and console lines)
580 aaa authentication login default tacacs+
582 NOTE: As soon as you issue this command, you will no longer be able to
583 create new logins to your NAS without a functioning tacacs+ daemon
584 appropriately configured with usernames and password, so make sure you
587 As a safety measure while setting up, we suggest you configure an
588 enable secret and make it the last resort authentication method, so
589 if your tacacs+ daemon fails to respond you will be able to use the
590 NAS enable password to login. To do this, configure:
593 aaa authentication login default tacacs+ enable
595 If all else fails, and you find yourself locked out of the NAS due to
596 a configuration problem, the section on "recovering from lost
597 passwords" on Cisco's CCO web page will help you dig your way out.
599 CONFIGURING ENABLE PASSWORDS
600 ----------------------------
602 The default privilege level for an ordinary user on the NAS is usually
603 1. When a user enables, she can reset this level to a value between 0
604 and 15 by using the NAS "enable" command. If she doesn't specify a
605 level, the default level she enables to is 15.
607 You can enable via tacacs+ e.g. by configuring on the NAS:
609 aaa authentication enable default tacacs+
611 then whenever you attempt to enable, an authentication request is sent
612 with the special username $enab<n>$ where <n> is the privilege level
613 you are attempting to enable to.
615 (Note: in order to be compatible with earlier versions of tacacs, when
616 the requested enable level is 15, the daemon will also try the
617 username $enable$ before trying username $enab15$).
619 For example, with the above declaration, in order to enable on the
620 NAS, you need a user declaration like this one, on the daemon:
623 login = cleartext "the enable password for level 15"
626 Note: Be aware that this does have the side effect that you now have a
627 user named $enab15$ who can then login to your NAS if she knows the
630 Here is a similar declaration allowing users to enable to level 4:
633 login = des bsoF4OivQCY8Q
636 CONFIGURING AUTHORIZATION
637 -------------------------
639 Authorization must be configured on both the NAS and the daemon to
640 operate correctly. By default, the NAS will allow everything until you
641 configure it to make authorization requests to the daemon.
643 On the daemon, the opposite is true: The daemon will, by default, deny
644 authorization of anything that isn't explicitly permitted.
646 Authorization allows the daemon to deny commands and services
647 outright, or to modify commands and services on a per-user
648 basis. Authorization on the daemon is divided into two separate parts:
649 commands and services.
654 Exec commands are those commands which are typed at a Cisco exec
655 prompt. When authorization is requested by the NAS, the entire command
656 is sent to the tac_plus daemon for authorization.
658 Command authorization is configured by specifying a list of
659 egrep-style regular expressions to match command arguments (see the
660 supplied man page, regexp.3, for a full description of regular
661 expressions) and an action which is "deny" or "permit".
663 The following configuration example permits user Fred to run the
666 telnet 131.108.13.<any number> and
667 telnet 128.<any number>.12.3 and
670 All other commands are denied (by default).
675 # permit specified telnets
676 permit 131\.108\.13\.[0-9]+
677 permit 128\.[0-9]+\.12\.3
680 # permit show commands
685 NOTE: If an argument list you specify contains spaces or tabs, you
686 must enclose it in double quotes.
688 The command and arguments which the user types gets matched to the
689 regular expressions you specify in the configuration file (in order of
690 appearance). The first successful match performs the associated
691 action (permit or deny). If there is no match, the command is denied
694 Conversely, the following configuration example can be used to deny
697 telnet 131.108.13.<any number>
699 and permit all other arguments, since the last line will match any
700 argument list. All other commands and services are permitted due to
701 the "default service = permit" clause.
703 Note: the default statement must be the first in the user clause
706 default service = permit
708 # allow all fred's telnet commands except to 131.108.13.*
709 deny 131\.108\.13\.[0-9]+
714 Note: Matches are not anchored, so "deny 131.108.13.[0-9]+" matches
715 anywhere in the command. To anchor the match, use ^ at the beginning
716 of the regular expression.
718 Note: When a command has multiple arguments, users may enter them in
719 many different permutations. It can be cumbersome to create regular
720 expressions which will reliably authorize commands under these
721 conditions, so administrators may wish to consider other methods of
722 performing authorization e.g. by configuring NAS-local privileged
723 enable levels on the NAS itself.
728 For command authorization, the Cisco NAS expands all commands to their
729 full names e.g. when you type "config t" on the NAS, this will be
730 expanded to "configuration terminal" before being sent to the daemon
731 so that you don't need to list all the possible contractions of a
734 CONFIGURING DEFAULT AUTHORIZATION
735 ---------------------------------
737 There are 3 places where defaults for authorization may be
738 configured. Unless specified to the contrary, the default is always to
741 1). To override the default denial of authorization for users who are
742 not explicitly listed in the configuration file, the ersatz user
743 DEFAULT, if defined, can be used for authorizing such users, viz:
745 default authentication = file /etc/passwd
748 service = ppp protocol = ip {
753 In this example, users who do not appear elsewhere will be
754 authenticated via the /etc/passwd file, and authorized by the contents
755 of the user = DEFAULT entry.
757 Note: For backward compatibility, the directive,
759 default authorization = permit
761 may still be specifed at the top level of the configuration file. This
762 overrides the default denial of authorization for users who are not
763 explicitly listed in the configuration file, permitting all
764 authorization requests for such users.
766 2). At the user level i.e. inside the braces of a user declaration,
767 the default for a user who doesn't have a service or command
768 explicitly authorized is to deny that service or command. The
769 following directive will permit the service or command by default
773 default service = permit
776 NOTE: This directive must appear first inside the user declaration.
778 3). At the service authorization level i.e. inside the braces of a
779 service declaration, arguments in an authorization request are
780 processed according to the algorithm described later. Some actions
781 when authorizing services (e.g. when matching attributes are not
782 found) depend on how the default is configured. The following
783 declaration changes the default from deny to permit for this user and
788 default attribute = permit
792 NOTE: This directive must appear before any others inside the service
795 NOTE: for command authorization (as opposed to service authorization
796 being discussed here), you specify deny .* or permit .* as the last
797 line of the regular expression matches to create default behavior.
799 AUTHORIZING EXEC STARTUP
800 -------------------------
802 If you authorize some exec commands, you implicitly agree to allow
803 that user to start an exec (it doesn't make sense to permit exec
804 commands if an exec can't be started to run those commands)
806 In addition to agreeing to allow an exec to start, you can supply some
807 parameters whenever an exec starts e.g. an autocommand, a dialback
808 string or a connection access list (acl).
810 In the example below, when an exec is started on the NAS, an acl of 4
811 will be returned to the NAS:
815 # this following line permits an exec to start and permits
816 # all commands and services by default
818 default service = permit
821 # When an exec is started, its connection access list will be 4.
822 # It also has an autocmd.
824 autocmd = "telnet foobar"
828 # allow all fred's telnet commands except telnet to 131.108.13.*
829 deny 131\.108\.13\.[0-9]+
834 NOTE: specifying an autocommand, or any other exec services, is part
835 of EXEC AUTHORIZATION. For it to work, you must also configure exec
836 authorization on your NAS e.g.
838 aaa authorization exec tacacs+
841 AUTHORIZING EXEC, SLIP, PPP and ARAP SERVICES
842 ----------------------------------------------
844 Authorizing exec, slip, PPP and arap services is done quite
845 differently from command authorization.
847 When authorizing these services, the NAS sends a request containing a
848 number of attribute-value (AV) pairs, each having the form
852 (Note: during debugging, you may see AV pairs whose separator
853 character is a "*" instead of a "=" sign. This is to signify that the
854 value in a pair is optional. An "=" sign indicates a mandatory
855 value. A "*" denotes an optional value).
857 e.g. a user starting ppp/ip using an address of 131.108.12.44 would
858 generate a request with the following AV pairs:
864 You can use the NAS debugging command
866 debug aaa authorization
868 to see what authorization AV pairs are being used by the NAS. Note: If
869 you are not on the router console, you will also need to issue a
870 'terminal monitor' command to see debug output.
872 THE AUTHORIZATION PROCESS
873 -------------------------
875 Authorizing a single session can result in multiple requests being
876 sent to the daemon. For example, in order to authorize a dialin ppp
877 user for IP, the following authorization requests will be made from
880 1). An initial authorization request to startup ppp from the exec,
881 using the AV pairs service=ppp, protocol=ip, will be made (Note: this
882 initial request will be omitted if you are autoselecting ppp, since
883 you won't know the username yet).
885 This request is really done to find the address for dumb PPP (or SLIP)
886 clients who can't do address negotiation. Instead, they expect you to
887 tell them what address to use before PPP starts up, via a text message
888 e.g. "Entering PPP. Your address is 1.2.3.4". They rely on parsing
889 this address from the message to know their address.
891 2). Next, an authorization request is made from the PPP subsystem to
892 see if ppp's LCP layer is authorized. LCP parameters can be set at
893 this time (e.g. callback). This request contains the AV pairs
894 service=ppp, protocol=lcp.
896 3). Next an authorization request to startup ppp's IPCP layer is made
897 using the AV pairs service=ppp, protocol=ipcp. Any parameters returned
898 by the daemon are cached.
900 4). Next, during PPP's address negotiation phase, each time the remote
901 peer requests a specific address, if that address isn't in the cache
902 obtained in step 3, a new authorization request is made to see if the
903 peers requested address is allowable. This step can be repeated
904 multiple times until both sides agree on the remote peer's address or
905 until the NAS (or client) decide they're never going to agree and they
906 shut down PPP instead.
908 As you can see from the above, a program which plans to handle
909 authorization must be able to handle a variety of requests and respond
912 AUTHORIZATION RELIES ON AUTHENTICATION
913 --------------------------------------
915 Since we pretty much rely on having a username in authorization
916 requests to decide which addresses etc. to hand out, it is important
917 to know where the username for a PPP user comes from. There are
918 generally 2 possible sources
920 1). You force the user to authenticate by making her login to the exec
921 and you use that login name in authorization requests. This username
922 isn't propagated to PPP by default. To have this happen, you generally
923 need to configure the "if-needed" method, e.g.
925 aaa authentication login default tacacs+
926 aaa authentication ppp default if-needed
929 2). Alternatively, you can run an authentication protocol, PAP or CHAP
930 (CHAP is much preferred), to identify the user. You don't need an
931 explicit login step if you do this (so it's the only possibility if
932 you are using autoselect). This authentication gets done before you
933 see the first LCP authorization request of course. Typically you
934 configure this by doing:
936 aaa authentication ppp default tacacs+
938 ppp authentication chap
940 If you omit either of these authentication schemes, you will start to
941 see authorization requests in which the username is missing.
943 CONFIGURING SERVICE AUTHORIZATION
944 ---------------------------------
946 A list of AV pairs is placed in the daemon's configuration file in
947 order to authorize services. The daemon compares each NAS AV pair to
948 its configured AV pairs and either allows or denies the service. If
949 the service is allowed, the daemon may add, change or delete AV pairs
950 before returning them to the NAS, thereby restricting what the user is
953 The complete algorithm by which the daemon processes its configured
954 AV pairs against the list the NAS sends, is given below.
956 The Authorization Algorithm
957 ---------------------------
959 Find the user (or group) entry for this service (and protocol), then
960 for each AV pair sent from the NAS:
962 If the AV pair from the NAS is mandatory:
964 a). look for an exact attribute,value match in the user's
965 mandatory list. If found, add the AV pair to the output.
967 b). If an exact match doesn't exist, look in the user's
968 optional list for the first attribute match. If found, add the
969 NAS AV pair to the output.
971 c). If no attribute match exists, deny the command if the
972 default is to deny, or,
974 d). If the default is permit, add the NAS AV pair to the
977 If the AV pair from the NAS is optional:
979 e). look for an exact attribute,value match in the user's
980 mandatory list. If found, add DAEMON's AV pair to output.
982 f). If not found, look for the first attribute match in the
983 user's mandatory list. If found, add DAEMONS's AV pair to output.
985 g). If no mandatory match exists, look for an exact
986 attribute,value pair match among the daemon's optional AV
987 pairs. If found add the DAEMON's matching AV pair to the
990 h). If no exact match exists, locate the first attribute match
991 among the daemon's optional AV pairs. If found add the
992 DAEMON's matching AV pair to the output.
994 i). If no match is found, delete the AV pair if the default is
997 j). If the default is permit add the NAS AV pair to the output.
999 k). After all AV pairs have been processed, for each mandatory
1000 DAEMON AV pair, if there is no attribute match already in the
1001 output list, add the AV pair (but add only ONE AV pair for each
1002 mandatory attribute).
1004 RECURSIVE AUTHORIZATION
1005 -----------------------
1007 Remember that authorization is also recursive over groups, in the same
1008 way that password lookups are recursive. Thus, if you place a user in
1009 a group, the daemon will look in the group for authorization
1010 parameters if it cannot find them in the user declaration.
1015 key = "your key here"
1018 login = des mEX027bHtzTlQ
1019 name = "Fred Flintstone"
1020 member = administrators
1021 expires = "May 23 2005"
1022 arap = cleartext "Fred's arap secret"
1023 chap = cleartext "Fred's chap secret"
1026 # When Fred starts an exec, his connection access list is 5
1029 # We require this autocmd to be done at startup
1030 autocmd = "telnet foo"
1033 # All commands except show system are denied for Fred
1036 # Fred can run the following show command
1042 service = ppp protocol = ip {
1043 # Fred can run ip over ppp only if he uses one
1044 # of the following mandatory addresses. If he supplies no
1045 # address, the first one here will be mandated
1052 # Fred's mandatory input access list number is 101
1055 # We will suggest an output access list of 102, but the NAS may
1056 # choose to ignore or override it
1063 # Fred can run slip. When he does, he will have to use
1064 # these mandatory access lists
1073 # Wilma has no password of her own, but she's a group member so
1074 # she'll use the group password if there is one. Same for her
1075 # password expiry date
1082 # group members who don't have their own login password will be looked
1085 login = file /etc/passwd
1087 # group members who have no expiry date set will use this one
1089 expires = "Jan 1 1997"
1093 CONFIGURATION RESPECTING NAS HOST OF THE USER
1094 ---------------------------------------------
1096 Sometimes you would want to modify the configuration file according to the
1097 source NAS where the user is being authenticated/authorized. For example if you
1098 are big ISP you want to permit administrator of company X to be able to monitor
1099 status of the links on NAS in company X but, of course, she should be able to
1100 monitor any other links on any other NAS of the same ISP. As all the NASes are
1101 authorized from the same Daemon, it seems as a problem. (You can workaround it
1102 by using custom authorization program - see "USING PROGRAMS TO DO
1103 AUTHORIZATION" section below - but it is not nice solution.)
1105 For this purposes there exists another entity 'host':
1112 As you can see you may use either IP address or DNS name. Anyway, we strongly
1113 recommend to always use only IP addresses - DNS subsystem may fail or it may be
1114 forged by the enemy.
1116 You have two methods of utilizing the differences between NASes:
1118 1) Current user is always automatically enlisted (=given membership to) to its
1119 current NAS host. This looks weird as only groups can have members but this
1120 is the only exception to this rule, current NAS host can really have a
1123 ( user "current_user" | user DEFAULT )
1125 +-- host "current_NAS_IP_address"
1129 +-- host "current_NAS_hostname"
1135 Each link only exists in the case it there exist both its peers, of course.
1136 user/group DEFAULT is written here only for the completeness of the chart.
1137 DEFAULT is discussed elsewhere in this documentation.
1139 According to the shown ordering, attributes/values in the host of current
1140 NAS identified by its IP address has _higher_ precence over the attributes
1141 in the current NAS identified by its (reverse-resolved) hostname.
1143 According to this auto-connections, you can for example permit some command
1144 to ALL the users on such NAS:
1147 login = cleartext LLLL
1149 host = machine.A.company {
1155 In this configuration file ALL the valid users can do "write terminal" when
1156 logged in on NAS "machine.A.company".
1158 2) Sometimes you need to do the authorization specific only to some users on
1159 some NASes. For example to permit "write terminal" ONLY to user fred
1160 connected to NAS "machine.A.company". That means that you want to forbid it
1161 to user fred on any other NAS and yuo also want to forbid it to all the
1162 other users on NAS "machine.A.company". (Line "authorization = recursive" is
1163 required but read the following section "FULL RECURSIVITY" to know all its
1166 authorization = recursive
1168 login = cleartext LLLL
1170 host = machine.A.company {
1178 This file has the same effect as:
1180 authorization = recursive
1182 login = cleartext LLLL
1183 when = host machine.A.company {
1190 You can see the (nested) command "when" can limit the scope of existence of
1191 its contents. Definition of "host machine.A.company" with empty block (no
1192 attributes) isn't needed as "when" line will automatically create hosts not
1193 defined elsewhere, in the same style as "enlist" keyword creates them. Any
1194 "user"s or "group"s referenced by "when" MUST be defined, such entities are
1195 never created automatically!
1197 Unfortunately you cannot use "when" to limit any items, just a few of them
1203 cmd arguments (to limit specific "permit"/"deny" lines)
1204 service (or incl. "protocol" specification)
1205 service AV pairs (to limit specific "attr=value" lines)
1206 when (enabling pure nesting of "when" blocks)
1208 Full flexibility to limit any contents may be done in future (needs complete
1209 cfgfile.c rewrite) but currently it is not supported. Fortunately you can
1210 get the same behaviour by appropriate usage of "member" keyword - all the
1211 attributes to be conditioned are put into separate group and you limit only
1212 the "member" keyword to such group.
1214 "when" command has the form "when = CONDITION { BLOCK }", CONDITION can be:
1216 user USR i.e. that current user is "USR")
1217 host HOSTNAME i.e. that current user is on NAS "HOSTNAME")
1218 group GRP i.e. current user belongs to the group "GRP",
1219 All possible "when" conditions to reach such belonging
1220 have to be successfuly met to make this condition successful.
1221 Realize that "member" can be limited by "when" keyword.
1222 CONDITION and CONDITION and CONDITION ...
1223 CONDITION or CONDITION or CONDITION ...
1227 You can see that you CANNOT use for example "user A and user B or user C",
1228 such condition would have ambiguous precedence of operators, you must
1229 explicitly write: ( user A and user B ) or user C
1230 or: user A and ( user B or user C )
1232 Both parentheses have to be written as separate words, NOT "(user A)"
1233 but "( user A )" instead.
1234 (Proper solution would also need the complete cfgfile.c rewrite.)
1236 "not" operator has the highest precendence, so: not user A or user B
1237 has the same meaning as: ( not user A ) or user B
1239 Sometimes the "when" condition is so-called unresolvable. Example:
1248 It is looping, when we would be the member of GRP, we would be really the
1249 member of GRP but otherwise sould wouldn't be the member of GRP. Weird?
1250 Yes, such case is considered as configuration bug, it is reported as:
1252 Unable to resolve expression from line 243, some looping occured
1254 Generally such unresolvable conditional expression is considered as UNKNOWN
1255 and the "when" keyword is then evaluated as "false" (=skip it's block).
1256 This MAY produce unwanted privilege access (if you were conditionally
1257 forbidding some privileges) so always watch out all the error messages in
1258 logs! (You should generally do default deny and specifically only "permit"
1259 all the privileges so the unintentional unresolvable expressions shouldn't
1265 We have written in the previous examples line:
1267 authorization = recursive
1269 This changes some behaviour of Daemon:
1271 1) Looping of memberships: By default any looped memberships are reported as
1272 error with message: recursively defined groups: ...
1274 After "authorization = recursive" any looping is silently accepted as it
1275 would be sometimes hard to prevent it in some complex configurations.
1276 Searching is done in normal Depth-First Search, but traversion is
1277 backtracked one step when the entity was already visited. Simply it will
1278 work 'magically', just safely ignore the fact.
1280 2) "default service = default" is supported only with:
1281 authorization = recursive
1282 This isn't any real change, just some formality. In fact each entity block
1283 has "default service = default" in effect as default (in the case you don't
1284 write any "default service =" assign).
1286 "authorization = recursive" is enforced here due to the change of Daemon
1287 behaviour: In non-recursive (old) case the Daemon assumes "deny .*" as the
1288 last line of "cmd" block. This makes proper NAS-host based permissions
1289 impossible. In "authorization = recursive" mode it requires appropriate
1290 "permit" or "deny" line to apply - otherwise the Depth-First Search through
1291 the entities will continue to find another applicable "cmd" block (toplevel
1292 "default authorization" may get into effect as the last resort).
1294 "default service" keyword takes then another meaning: In non-recursive mode
1295 it will mean "if the command wasn't found". In fully-recursive mode it will
1296 mean "if any cmd block didn't decide".
1298 Please keep in mind that "service =" (with its possible "protocol =" mate)
1299 has always the same behaviour, nothing is changed with "authorization =
1300 recursive" enabled. Its functionality is already a bit complex (with AV
1301 pairs get erased, which added, which copied, which are optional from NAS,
1302 which optional from Daemon, whether to do default permit or deny etc.).
1303 Fortunately we didn't found that there would be needed some extended
1304 'recursiveness' functionality of "service" for application of NAS-host based
1307 3) "host" entities are not recursive at all (=its attributes aren't looked up
1308 in its parent groups) without "authorization = recursive". This isn't any
1309 much change as in the previous versions of Daemon "host" entity was either
1310 completely unsupported or it was supported only with the only one attribute:
1312 "key": Attribute defines different protocol key (instead of the specified
1313 toplevel one) for the specified host. Its use is recommended to
1314 improve overall network security (by using unique key for each NAS).
1316 USING PROGRAMS TO DO AUTHORIZATION
1317 ----------------------------------
1319 There are some limitations to the authorization that can be done using
1320 a configuration file. The main ones are that you're constrained by the
1321 algorithm the daemon uses, and that the configuration is basically
1322 static, so if you're trying to use it to allocate dynamic things (such
1323 as addresses from a pool) that vary over time, you need another
1326 One solution is to arrange for the daemon to call your own
1327 user-supplied programs to control authorization. These "callouts"
1328 permit almost complete control over authorization, allowing you to
1329 read all the fields in the authorization packet sent by the NAS
1330 including all its AV pairs, and to set authorization status and send a
1331 new set of AV pairs to the NAS in response.
1333 USING AV PAIRS FOR AUTHORIZATION
1334 --------------------------------
1336 During authorization, the NAS sends an authorization request packet
1337 containing various fields of interest and a set of AV pairs (see the
1338 tacacs+ protocol specification for a list of fields and pairs).
1340 Fields from the authorization packet can be supplied to the programs
1341 you call on their command line, by using the appropriate dollar
1342 variables in the configuration file (see below).
1344 AV pairs from the authorization packet are fed to the program's
1345 standard input, one per line. The program is expected to process the
1346 AV pairs and write them to its standard output, one per line. What
1347 happens then is determined by the exit status of the program.
1349 NOTE: AV pairs are text strings with the format
1350 attribute=value. Unlike the configuration file which allows spaces
1351 when specifying AV pairs, there should be no spaces surrounding the
1352 "=" sign when using the programmatic interface.
1354 CALLING SCRIPTS BEFORE AUTHORIZATION
1355 ------------------------------------
1357 You can specify a per-user program to be called before any other
1358 attempt to authorize is made by using a "before" clause e.g.
1361 before authorization "/usr/bin/pre_authorize $user $port $address"
1364 The AV pairs sent from the NAS will be supplied to this program's
1365 standard input, one pair per line.
1367 Fields from the initiating authorization packet which the NAS sends to
1368 the daemon can also be passed to the program by using dollar variables
1369 in the command line. A complete list of available variables is as
1370 follows (consult the API specification for more details).
1375 address -- Nac address (remote user location)
1376 priv -- privilege level (a digit, 0 to 15)
1377 method -- (a digit, 1 to 4)
1378 type -- (a digit, 1 to 4)
1379 service -- (a digit, 1 to 7)
1380 status -- (pass, fail, error, unknown)
1382 Unrecognized variables will appear as the string "unknown".
1384 If the program returns a status of 0, authorization is unconditionally
1385 permitted. No further processing is done on this request and no AV
1386 pairs are returned to the NAS.
1388 If the program returns a status of 1, authorization is unconditionally
1389 denied. No further processing is done on this request and no AV pairs
1390 are returned to the NAS.
1392 If the program returns a status of 2, authorization is permitted. The
1393 program is expected to modify the AV pairs that it receives on its
1394 standard input (or to create entirely new ones) and to write them, one
1395 per line, to its standard output. The new AV pairs will be sent to the
1396 NAS with a status of AUTHOR_STATUS_PASS_REPL. No further processing
1397 takes place on this request.
1399 If the program returns a status of 3, authorization is denied, but all
1400 attributes returned by the program via stdout are returned to the
1401 NAS. Also, whatever the program returns on stderr is placed into the
1402 server-msg field and returned to the NAS as well.
1404 Any other status value returned from the program will cause an error
1405 to be returned to the NAS.
1407 Note that a status of 2 is not acceptable when doing command
1410 CALLING PROGRAMS AFTER AUTHORIZATION
1411 ------------------------------------
1413 You can specify a per-user program to be called after authorization
1414 processing has been carried out by the daemon (but before the
1415 authorization status and AV pairs have been transmitted to the NAS).
1417 The program can optionally modify the AV pairs being sent back to the
1418 NAS and change the authorization status if required.
1421 # call /usr/bin/post_authorize passing it the username, port
1422 # and current authorization status.
1423 after authorization "/usr/bin/post_authorize $user $port $status"
1426 The AV pairs resulting from the authorization algorithm that the
1427 daemon proposes to return to the NAS, are supplied to the program on
1428 standard input, one AV pair per line, so they can be modified if
1431 Fields from the incoming authorization packet which the NAS sent to
1432 the daemon can also be passed to the program on its command line by
1433 specifying dollar variables in the command line (see previous
1436 The program is expected to process the AV pairs and write them to its
1437 standard output, one per line. What happens then is determined by the
1438 exit status of the program:
1440 If the program returns a status of 0, authorization continues as if
1441 the program had never been called. Use this if e.g. you just want a
1442 program to send mail when an authorization occurs, without otherwise
1443 affecting normal authorization.
1445 If the program returns a status of 1, authorization is unconditionally
1446 denied. No AV pairs are returned to the NAS. No further authorization
1447 processing occurs on this request.
1449 If the program returns a status of 2, authorization is permitted and
1450 any AV pairs returned from the program on its standard output are sent
1451 to the NAS in place of any AV pairs that the daemon may have
1454 Any other value will cause an error to be returned the the NAS by the
1457 WARNINGS AND CAUTIONS
1458 ---------------------
1460 Customers attempting to write authorization scripts will find the NAS
1461 debugging command "debug aaa authorization" invaluable.
1463 Pre and post authorization programs are invoked by handing the command
1464 line to the Bourne shell. On many Unix systems, if the shell doesn't
1465 find the specified program it returns a status of one, which denies
1466 authorization. However, at least one Unix system (BSDI) returns a
1467 status code of 2 under these circumstances, which will permit
1468 authorization, and probably isn't what you intended.
1470 Note also that if your program hangs, the authorization will time out
1471 and return an error on the NAS, and you'll tie up a process slot on
1472 the daemon host, eventually running out of resources. There is no
1473 special code to detect this in the daemon.
1475 Unless you make special arrangements, the daemon will run as root and
1476 hence the programs it invokes will also run as root, which is a
1477 security weakness. It is strongly recommended that you use absolute
1478 pathnames when specifying programs to execute, and that you use the
1479 Makefile options TAC_PLUS_USERID and TAC_PLUS_GROUPID so that the
1480 daemon is not running as root when calling these programs,
1482 The daemon communicates with pre and post authorization programs over
1483 a pair of pipes. Programs using the standard i/o library will use full
1484 buffering in these circumstances. This shouldn't be a problem for most
1485 programs, since they'll read AV pairs till they see end of file on
1486 input, and they'll flush all output when they exit.
1488 Note that when avpairs containing spaces are listed in the
1489 configuration file, you need to enclose them in double quotes so that
1490 they are parsed correctly. Avpairs which are returned via standard
1491 output do not need delimiters and so should not be enclosed in double
1494 CONFIGURING AUTHORIZATION ON THE NAS
1495 ------------------------------------
1497 If authorization is not explicitly configured on the NAS, no
1498 authorization takes place i.e. effectively, everything is
1499 permitted. Note that this is the converse of what happens on the
1500 daemon, where anything not explicitly permitted is denied by default.
1502 To configure command authorization on the NAS, issue the following NAS
1503 configuration commands:
1505 aaa authorization commands 1 tacacs+
1506 aaa authorization commands 15 tacacs+
1509 This will make the NAS send tacacs+ requests for all level 1 (ordinary
1510 user) and level 15 (privileged level) commands on all lines/interfaces.
1512 NOTE: As soon as you configure the above on your NAS, you will only be
1513 permitted to execute NAS commands which are permitted by your tacacs+
1514 daemon. So make sure you have configured, on the daemon, an
1515 authenticated user who is authorized to run commands, or you will be
1516 unable to do much on the NAS after turning on authorization.
1518 Alternatively, or in addition, you may also want to configure the
1521 aaa authorization commands 1 tacacs+ if-authenticated
1523 This will use tacacs+ authorization for level 1 (user-level commands)
1524 but if problems arise, you can just switch off the tacacs+ server and
1525 authorization will then be granted to anyone who is authenticated.
1527 The following daemon configuration should be sufficient to ensure that
1528 you can always login as username "admin" (with a suitable password)
1529 and run any command as that user:
1532 default service = permit
1533 login = des kppPfHq/j6gXs
1540 There is only one configurable accounting parameter -- the accounting
1541 file name. All accounting records are written, as text, to this
1542 filename. The filename is configured as follows at the top-level of
1543 the configuration file:
1545 accounting file = <filename>
1547 Since accounting requests occur (and are serviced) asynchronously, it
1548 is necessary to lock the accounting file so that two writers don't
1549 simultaneously update it. The daemon uses the fcntl call to do this
1550 locking, so it is recommended that the accounting file reside on a
1551 local filesystem. Although fcntl locking over NFS is supported on some
1552 Unix implementations, it is notoriously unreliable. Even if your
1553 implementation is reliable, locking is likely to be extremely
1554 inefficient over NFS.
1559 To get accounting records equivalent to previous versions of tacacs,
1560 the following is sufficient. "Stop" records contain elapsed time for
1561 connections and exec sessions.
1563 aaa accounting network stop-only tacacs+
1564 aaa accounting exec stop-only tacacs+
1567 CONFIGURING CALLBACK WITH TACACS+
1568 ---------------------------------
1570 Note: Callback is available only in IOS 11.1 and later, and can only
1571 be controlled via Tacacs+ for ASYNC lines. ISDN callback can be
1572 configured on the NAS but cannot be controlled via AAA.
1574 Here is an example of AAA configuration (with exec and network
1575 accounting enabled):
1580 tacacs-server host XX.XX.XX.XX
1581 tacacs-server key fookey
1582 aaa accounting exec wait-start tacacs+
1583 aaa accounting network wait-start tacacs+
1585 ! Example of AAA configuration for Exec:
1586 aaa authentication login execcheck tacacs+
1587 aaa authorization network tacacs+
1588 service exec-callback
1591 login authentication execcheck
1593 ! Example of AAA configuration for ARAP:
1594 aaa authentication arap arapcheck tacacs+
1595 aaa authorization network tacacs+
1599 arap authentication arapcheck
1601 ! Example of AAA-specific configuration for PPP callback:
1603 aaa authentication ppp pppcheck tacacs+
1604 aaa authorization network tacacs+
1607 ppp authentication chap pppcheck
1610 Daemon configuration:
1612 Example of remote TACACS+ server CONFIG file entry for username `foobar':
1615 arap = cleartext AAAA
1616 login = cleartext LLLL
1617 chap = cleartext CCCC
1618 pap = cleartext PPPP
1619 opap = cleartext OOOO
1620 service = ppp protocol = lcp {
1621 callback-dialstring=123456
1624 callback-dialstring=2345678
1627 callback-dialstring=3456789
1636 DEBUGGING CONFIGURATION FILES
1637 -----------------------------
1639 When creating configuration files, it is convenient to check their
1640 syntax using the -P flag to tac_plus e.g.
1642 tac_plus -P -C <config file name>
1644 will syntax check the configuration file and print any error messages
1647 DEBUGGING A RUNNING SERVER
1648 --------------------------
1650 There is a myriad of debugging values that can be used in conjunction
1651 with the -d flag to produce debugging output in /var/log/tac_plus.log.
1653 For example, starting the daemon with
1655 tac_plus -C CONFIG -d 16
1657 will put authentication debugging into /var/log/tac_plus.log. You can
1658 view this information by using the tail command.
1660 tail -f /var/log/tac_plus.log
1662 See the man page for more information.
1664 CHANGING CONFIGURATIONS
1665 -----------------------
1667 To change a configuration file, you must edit the configuration file
1668 and then send the daemon a SIGUSR1. This will cause it to reinitialize
1669 itself and re-read the configuration file.
1671 On startup, tac_plus creates the file /var/run/tac_plus.pid , if possible,
1672 containing its process id. If you invoke the daemon so that it listens
1673 on a non-standard port, the file created is /var/run/tac_plus.pid.<port>
1674 instead, where <port> is the port number the daemon is listening on.
1676 Assuming you are listening on the default port 49, something like the
1677 following should work:
1679 # kill -USR1 `cat /var/run/tac_plus.pid`
1681 It's a good idea to check that the daemon is still running after
1682 sending it a SIGUSR1, since a syntactically incorrect configuration
1683 file will cause the daemon to die.
1685 NOTE: The perl script generate_passwd.pl may be used to hand-generate
1686 encrypted passwords, or they may be taken from a Unix passwd file.
1688 FREQUENTLY ASKED QUESTIONS
1689 --------------------------
1690 Q). Does T+ required a working DNS?
1692 A). As distributed, whenever a START packet arrive, the daemon makes a
1693 call to getpeername to find out the name of the requestor. Depending
1694 entirely on how your Unix host is set up, this may make DNS
1695 queries. If this is a problem, comment out the code in tac_plus.c
1696 which does this, and just use ip addresses instead of host names.
1698 Q). Is the "name" field used for anything
1700 A). No. It's purely for documentation. I had once thought it might be
1701 useful when outputting error messages, and that you might need the
1702 information if you converted a passwd(5) style file, but no use is
1703 currently made of the field.
1705 Q). Why do I get PPP authorization failures because of "no username in
1706 request" when I've already logged in and authenticated?
1708 A). With "aaa authentication PPP default tacacs+", the ppp
1709 authentication overrides the earlier login authentication. If the ppp
1710 authentication fails, the username ends up blank. Changing the config
1711 to "aaa authentication ppp default if-needed tacacs+" fixes this
1714 Q). I'm sure I configured it correctly, but accounting still doesn't
1717 A). You will find that although you can configure accounting in 10.3,
1718 and it outputs debug messages, it doesn't send any accounting
1719 packets. This is because Accounting only works from 11.0 onwards.
1721 Q). Does TACACS+ use a database instead of a flat (/etc/passwd like)
1722 file to decrease search times, say if we are talking about a large
1723 database of 40,000 users?
1725 A). The TACACS+ authentication database is held internally as a hash
1726 table. This makes lookup times fast and fairly linear, at the expense
1727 of making the server use potentially large amounts of memory space.
1728 NOTE: If you specify that the server uses passwd(5) files for
1729 authentication, then you don't get this speed benefit, but you save
1732 If you're willing to write the code, it should be a relatively simple
1733 matter to interface the code to a database scheme e.g. unix dbm files,
1734 or some proprietary database package, if you wish.
1736 Q). Is there any way to avoid having clear text versions of the
1737 ARAP and CHAP secrets in the configuration file?
1739 CHAP and ARAP require that the server knows the cleartext password (or
1740 equivalently, something from which the server can generate the
1741 cleartext password). Note that this is part of the definition of CHAP
1742 and ARAP, not just the whim of some Cisco engineer who drank too much
1743 coffee late one night.
1745 If we encrypted the CHAP and ARAP passwords in the database, then we'd
1746 need to keep a key around so that the server can decrypt them when
1747 CHAP or ARAP needs them. So this only ends up being a slight
1748 obfuscation and not much more secure than the original scheme.
1750 In extended TACACS, the CHAP and ARAP secrets were separated from the
1751 password file because the password file may be a system password file
1752 and hence world readable. But with TACACS+'s native database, there
1753 is no such requirement, so we think the best solution is to
1754 read-protect the files. Note that this is the same problem that a
1755 kerberos server has. If your security is compromised on the kerberos
1756 server, then your database is wide open. Kerberos does encrypt the
1757 database, but if you want your server to automatically restart, then
1758 you end up having to "kstash" the key in a file anyway and you're back
1759 to the same security problem.
1761 So storing the cleartext password on the security server is really an
1762 absolute requirement of the CHAP and ARAP protocols, not something
1765 We could have chosen a scheme where the NAS sends the challenge
1766 information to the TACACS+ daemon and the daemon uses the cleartext
1767 password to generate the response and returns that, but that means
1768 that we must include specific protocol knowledge into the protocol for
1769 both ARAP and CHAP and we would have to update the protocol every time
1770 a new authentication protocol is added. Hence we decided to go with
1771 the SENDPASS mechanism.
1773 Note that the above doesn't apply to PAP. You can keep an inbound PAP
1774 password des-encrypted, since all you need to do with it is verify
1775 that the password the principal gave you is correct.
1777 Q). How is the typical login authentication sequence done?
1779 A). NAS sends START packet to daemon
1780 Daemon send GETUSER containing login prompt to NAS
1781 NAS prompts user for username
1782 NAS sends pkt to daemon
1783 Daemon sends GETPASS containing password prompt to the NAS
1784 NAS prompts user for password
1785 NAS sends pkt to daemon
1786 Daemon sends accept, reject or error to NAS
1789 Q). Is there a GUI for the configuration file?
1790 A). No. Use your favourite text editor.
1793 Q). What does "default service = permit" really do?
1795 A). When a request comes in to authorize exec startup, or ppp (with
1796 protocol lcp, ip, ipx), or slip, or arap or a specific command, the
1797 daemon looks for a matching declarations for the user (or groups the
1798 user is a member of).
1800 For exec startup, it looks for a "service=exec" OR any command
1803 For ppp, it looks for a "service=ppp" and "protocol=(one of lcp, ip,
1806 For slip there must be a "service=slip" and for arap a "service=arap"
1809 For specific commands, there must be a matching cmd=<cmdname>.
1811 If these aren't found, authorization will fail, *unless* you say
1812 "default service = permit".
1814 Q). How do I make PAP work?
1816 A). Avoid using PAP if possible since it's not very secure. If you
1817 *must* use it, PAP passwords may be specified along with arap and chap
1818 passwords for each user. Note that the details of this changed in
1819 version 3.0 and onwards.
1821 For outbound PAP, where you are forced to send a password to the
1822 remote host to identify yourself, there is now a separate "opap"
1825 opap = cleartext OOOO
1827 You use this to set the outbound PAP password. It must be a cleartext
1830 NOTE: It is very bad practice to use an outbound PAP password that is
1831 the same as any of your inbound passwords. For this reason, a "global"
1832 password does not apply to outbound PAP, only to inbound PAP,
1833 bidirectional CHAP and ARAP.
1835 Before 3.0, PAP logins were treated like ordinary user logins, so you
1836 needed to declare a user in the Daemon configuration file whose name
1837 was typically the remote hostname (or user), with a login password, in
1838 order to process the PAP request.
1840 Q). How can I deny some one from telneting from a commserver by ip
1841 address only. i.e. when command is 10.0.1.6 rather than telnet
1844 A). The best way to restrict telnet access is by applying an outbound
1845 access list via the access class command (or equivalently, via the
1846 "acl" avpair). The NAS configuration command "access-class <n> out"
1847 for example applies a pre-defined standard IP access list (where n is
1848 a number from 1 through 99) that governs telnet access from a NAS.
1850 E.g. the following configuration commands permit outgoing Telnet
1851 access from line 1 on the NAS *only* to hosts on network 192.85.55.0:
1853 access-list 12 permit 192.85.55.0 0.0.0.255
1857 Note: you must define "access-list 12 permit 192.85.55.0 0.0.0.255" on
1858 the NAS. Only then can you use the acl avpair to apply it to a line
1859 that a user dials in on.
1861 Alternatively, you can try configuring "transport preferred none" on
1862 the lines in question. This will force a user to always type "telnet
1863 10.0.1.6" in order to telnet out from the NAS. Then you can apply
1864 command authorization to this command to restrict it.
1866 Q). I have an autocommand configured in the NAS-local database and I'm
1867 using "aaa authentication local-override". The autocommand doesn't
1868 work, but the username/password does. Why?
1870 A). The "local-override" only applies to the authentication portion of
1871 the local database, so if you want an autocommand for this user, you
1874 aaa authorization exec local if-authenticated
1876 This will use the local DB entry if one exists, allow authenticated
1877 users otherwise, or fail.
1879 We don't have a "aaa authorization local-override" like we do for
1880 authentication. Unlike authentication, the local method for
1881 authorization is sort of equivalent to a local-override.
1883 Q). Can tacacs+ only be enabled on a global basis? I want to
1884 selectively turn it on for, e.g. only modem-connected lines. How do I
1887 A). You turn tacacs+ ON on a global basis, but you can then change the
1888 behavior of individual lines to whatever you want, e.g.
1890 aaa authentication login default tacacs+ none
1891 aaa authentication login oldstyle line
1892 aaa authentication login none none
1894 login authentication default
1896 login authentication oldstyle
1898 login authentication none
1900 Note that unfortunately, you can't (yet) apply authorization
1901 differently to selected lines and interfaces.
1903 Q). I have leased lines running PPP, and AAA authorization is also
1904 configured, so the authorization on the leased lines fails. What should
1907 A). Since you can't (yet) configure authorization on a per-line basis,
1908 you have to turn on authentication on the leased lines running PPP and
1909 configure your T+ server so that it will authorize these lines
1912 A more demanding alternative is to modify the TACACS+ server source code
1913 to allow any authorizations coming in from the port "SerialXXX" to
1916 A third possibility is to not use PPP on those lines, e.g. use HDLC
1917 instead. HDLC doesn't require authentication or authorization.
1919 Q). What are the memory recommendations for TACACS+?
1921 A). Unless you're using passwd style files, TACACS+ holds entries in
1922 hash tables in memory. The overhead is modest e.g. each user entry
1923 occupies 72 bytes, plus space for strings like username and password
1924 etc. Access time should thus be pretty constant regardless of number
1925 of users. On a sparc 2, a config file containing 2000 users requires
1928 Q). How many users will a TACACS+ server support? What happens when
1929 the maximum is exceeded?
1931 There are 2 issues. The first is that each entry in the config file
1932 occupies memory (swap space) so you could run out of swap space either
1933 starting up the daemon or when it forks to answer incoming requests
1934 (see above). If this happens, the daemon will drop the connection
1935 which should appear as an error to the NAS) and the logfile will
1936 contain appropriate error messages. The solution is usually to add
1937 more disk space for swapping.
1939 The second issue is speed: Using config files containing 75,000 user
1940 entries, I'm seeing about 3 authentications per second on a sparc 2
1941 without noticeable performance impact, though I haven't benchmarked
1944 So more than about 3 authentications per second on this platform will
1945 result in users seeing delays and having to wait for prompts. The
1946 usual solution to this is to add more daemons to spread the load out.
1948 Q). How many characters may a TACACS+ Username and Password contain?
1950 A). The short answer is 31 bytes of username, with up to 254 bytes of
1951 password if they are cleartext (8 bytes if passwords are des
1954 The long answer is that the Cisco NAS allocates a buffer of 1024
1955 bytes, so this is the maximum you can type in, in response to a NAS
1958 But the protocol spec allows a username or password length field of
1959 just one byte in an authentication packet, so only the first 255 of
1960 these characters can be sent to the daemon.
1962 Then, the API spec states that the username in the identity structure
1963 on the daemon is 32 bytes long, so only the first 31 bytes of username
1964 will be copied from the authentication packet into this structure,
1965 which is then null-terminated.
1967 The password, on the other hand, is copied into malloc'ed memory, so
1968 it can still be up to 255 characters long.
1970 Now if it's a des encrypted password, then only the first 8 bytes are
1971 significant, per the common unix implementations of crypt.
1973 Lastly, there is also the question of how long a username/password can
1974 be configured in the daemon configuration file. The answer is given by
1975 the value of MAX_INPUT_LINE_LEN, currently set to 255, which
1976 determines the length of the longest string you can enter in the
1979 Q). What is the format of accounting records?
1981 Accounting records are text lines containing tab-separated fields. The
1982 first 6 fields are always the same. These are:
1984 timestamp, NAS name, username, port, address, record type.
1986 Following these, a variable number of fields are written, depending on
1987 the accounting record type. All are of the form attribute=value. There
1988 will always be a task_id field.
1990 Current attributes are:
2008 "callback-dialstring"
2013 I expect more will be added over time.
2015 Example records are thus:
2017 Thu Jul 13 13:35:28 1995 cherub.cisco.com chein tty5 171.69.1.141 stop task_id=12028 service=exec port=5 elapsed_time=875
2018 Thu Jul 13 13:37:04 1995 cherub.cisco.com lol tty18 171.69.1.129 stop task_id=11613 service=exec port=18 service=exec port=18 elapsed_time=909
2019 Thu Jul 13 14:09:02 1995 cherub.cisco.com billw tty18 171.69.1.152 start task_id=17150 service=exec port=18
2020 Thu Jul 13 14:09:02 1995 cherub.cisco.com billw tty18 171.69.1.152 start task_id=17150 service=exec port=18 service=exec port=18
2023 Elapsed time is in seconds, and is the field most people are usually
2026 Q). How do I limit the number of sessions a user can have?
2028 A). The TACACS+ daemon can enforce how many simultaneous sessions a
2029 given user is allowed to have. You must compile the daemon with the
2030 MAXSESS symbol defined (see the Makefile).
2032 Maximum sessions are configured on the daemon for a user as follows:
2035 login = cleartext XXX
2037 # only allow two sessions max for joeslip
2040 name = "Joe SLIP User"
2044 It can also be configured under a group:
2046 group = slip_users {
2057 The daemon keeps a count of how many sessions a given user owns by
2058 monitoring START and STOP accounting records. Thus, exec and network
2059 accounting must be configured for this feature to operate for exec and
2062 As the restriction is enforced during the authorization phase of
2063 login, exec and network authorization must be configured as well, viz:
2065 aaa authentication login default tacacs+
2066 aaa authentication ppp default tacacs+
2067 aaa authorization exec tacacs+
2068 aaa authorization network tacacs+
2069 aaa accounting exec start-stop tacacs+
2070 aaa accounting network start-stop tacacs+
2072 Due to network outages (or other disruptions), it is possible for the
2073 TACACS+ daemon's record of usage to become out of sync with reality,
2074 so before denying access because it thinks a user is running too many
2075 sessions, the TACACS+ daemon will use the finger service on the NAS to
2076 verify how many sessions a user is running there.
2078 If the result of finger indicates that the daemon should permit
2079 access, access will be granted. Note that for this check to work via
2080 finger, "service finger" must also be configured on the NAS.
2082 Lastly, note that because finger output truncates usernames at 10
2083 characters, you may encounter trouble if you have users whose names
2084 are not unique within those first 10 characters.
2086 Also recall that authorization works differently on the console. So
2087 many people locked themselves out of their boxes after configuring
2088 authorization, that we stopped requiring authorization on the console
2089 for authenticated users. Since there's no authorization on the
2090 console, MAXSESS is not enforced there.
2092 Q). How can I configure time-outs on an interface via Tacacs+?
2094 A). Certain per-user/per-interface timeouts may be set by Tacacs+
2095 during authorization. As of 11.0, you can set an arap session timeout,
2096 and an exec timeout. As of 11.1 you can also set an exec idle timeout.
2098 There are currently no settable timeouts for PPP or SLIP sessions, but
2099 there is a workaround which applies to ASYNC PPP/SLIP idle timeouts
2100 started via exec sessions only: This workaround is to set an EXEC
2101 (idletime) timeout on an exec session which is later used to start up
2102 PPP or SLIP (either via a T+ autocommand or via the user explicitly
2103 invoking PPP or SLIP). In this case, the exec idle timeout will
2104 correctly terminate an idle PPP or SLIP session. Note that this
2105 workaround cannot be used for sessions which autoselect PPP or SLIP.
2107 An idle timeout terminates a connection when the interface is idle for
2108 a given period of time (this is equivalent to the "session-timeout"
2109 Cisco IOS configuration directive). The other timeouts are
2110 absolute. Of course, any timeouts set by Tacacs+ apply only to the
2115 login = cleartext foobar
2117 # disconnect lol if there is no traffic for 5 minutes
2119 # disconnect lol unconditionally after one hour
2123 You also need to configure exec authorization on the NAS for the above
2126 aaa authorization exec tacacs+
2128 Note that these timeouts only work for async lines, not for ISDN
2132 Note also that you cannot use the authorization "if-authenticated"
2133 option with these parameters, since that skips authorization if the
2134 user has successfully authenticated.
2136 Q). How do I send VPDN forwarding decisions to an authorization
2139 A). In 11.2 onwards, VPDN NASs can use T+ to allow an authorization
2140 server to make the decision to forward users.
2142 If VPDN forwarding is turned on, and the username is of the form
2143 user@domain, and "domain" matches a vpdn outgoing configured domain,
2144 then an authorization attempt is made for "domain" (see below).
2146 When making an authorization call for VPDN, a service type of "ppp"
2147 with a protocol type of "vpdn", with a username of "domain" will be
2148 made e.g. when a PPP user comes up on a line with the username
2149 foo@bar.com, if "vpdn enable" and "aaa authorization ...." is enabled
2150 on the box, then a one-time authorization of the name "bar.com" is
2153 If this authorization is successful, no local authentication is
2154 attempted on the NAS, and the connection is forwarded via VPDN
2157 If no VPDN-specific information comes back from this authorization
2158 call, the login proceeds as follows:
2160 If tacacs-server directed-requests are configured (note: this is true
2161 by default), then IOS will strip off the domain part of a name of the
2162 form user@domain and use "domain" to try and select a T+ server. If
2163 successful, the username portion "user", without the domain, will be
2164 used for all subsequent authentication, authorization and accounting.
2166 If directed requests are turned off, then the entire username
2167 user@domain is treated as a username.
2169 vpdn specific information includes the attributes "tunnel-id",
2170 "source-ip" (deprecated) and "ip-addresses":
2173 This AV pair specifies the username that will be used to
2174 authenticate the tunnel over which the individual user MID
2175 will be projected. This is analogous to the "NAS name" in the
2176 "vpdn outgoing" command.
2179 This is a list of possible IP addresses that can be used for
2180 the end-point of the tunnel. Consult the text at the end of
2181 this document for more details on how to configure this
2184 source-ip: (This is now deprecated. It began in release 11.2(1.4),
2185 and was removed in 11.2(4.0.2)).
2186 This ip address will be used as the source of all VPDN packets
2187 generated as part of the VPDN tunnel (see the source-ip
2188 keyword in the vpdn outgoing command).
2193 The following syntax is used on the public domain Tacacs+ server.
2196 service = ppp protocol = vpdn {
2197 tunnel-id = <name for tunnel authentication>
2198 ip-addresses = <addr> [<addr> ...]
2199 source-ip = <ip-address>
2203 In addition the T+ server can be used to store the usernames for both
2204 the NAS (the username specified by "tunnel-id" above) and the Home
2205 Gateway. These will be used to authenticate the tunnel.
2209 user = foobar.cisco.com {
2210 service = ppp protocol = vpdn {
2212 ip-addresses = "173.20.12.19 173.20.12.20"
2213 source-ip = 173.5.10.1
2218 global = cleartext egad
2221 user = my_home_gateway {
2222 global = cleartext wowser
2228 To enable AAA assisted VPDN forwarding on a NAS, the following minimum
2229 configuration is required:
2233 aaa authorization network tacacs+ ...
2235 In addition, if the passwords for the home gateway and NAS are stored
2236 on the T+ daemon, the command
2238 aaa authentication login tacacs+ ....
2240 should also be present.
2242 Beginning with release 11.2(1.4), the additional configuration
2244 vpdn outgoing cisco.com ip NAS [ source-ip X.X.X.X ]
2246 can be used. This changes in 11.2(4.0.2) and becomes:
2248 vpdn source-ip X.X.X.X
2249 vpdn outgoing cisco.com ip NAS
2252 Q). Can someone expand on the use of the "optional" keyword.
2254 A). Most attributes are mandatory i.e. if the daemon sends them to the
2255 NAS, the NAS must obey them or deny the authorization. This is the
2256 default. It is possible to mark attributes as optional, in which case
2257 a NAS which cannot support the attribute is free to simply ignore it
2258 without causing the authorization to fail.
2260 This was intended to be useful in cutover situations where you have
2261 multiple NASes running different versions of IOS, some of which
2262 support more attributes than others. If you make the new attributes
2263 optional, older NASes could ignore the optional attributes while new
2264 NASes could apply them. Note that this weakens your security a little,
2265 since you are no longer guaranteed that attributes are always applied
2266 on successful authorization, so it should be used judiciously.
2268 Q). Can I do do address pooling on the T+ daemon?
2270 A). Not really since nothing on the daemon tracks whether an address
2271 is already in use. The best way to do manage address pools is to
2272 define a non-overlapping pool of addresses on each NAS and return the
2273 name of this pool during authorization whenever a user logs in e.g.
2277 ip local pool foo 1.0.0.1 1.0.0.10
2282 service = ppp protocol = ip {
2288 Q). What about MSCHAP?
2290 A). Version F4.X contains mschap support. Mschap is configured the
2291 same way as chap, only using the "mschap" keyword in place of the
2294 Like ARAP, MSCHAP works best when you have a des library (see the note
2295 at the beginning of this document), but this is optional, as the DES
2296 calculation can be done by the NAS instead. It also optionally
2297 requires a key from Microsoft which is not public domain, but this can
2298 also be done on the NAS too, so you can live without it.
2300 To compile the daemon with MSCHAP support, uncomment the MSCHAP line
2301 in the Makefile. This will add the MSCHAP code to your daemon. You can
2302 leave MSCHAP_DES undefined, in which case the MSCHAP DES calculation
2303 will be done by NAS, and no special MSCHAP key will be required.
2305 If you have a DES library and want to use it with MSCHAP (this is more
2306 efficient for authentication), then you can also uncomment the
2307 MSCHAP_DES and MSCHAP_MD4_SRC lines in the Makefile. This will ensure
2308 that the DES calculation done in the daemon. A key will need to be
2309 obtained from Microsoft and used to replace the definition of
2310 MSCHAP_KEY in the file mschap.h. If you're thinking by now that this
2311 is all too much trouble, I can't say I blame you....
2313 Q). Can I do wtmp-style logging like xtacacd used to do?
2315 A). Wtmp file logging is supported. The "-u <wtmpfilename>" command
2316 line flag can be used to specify a filename which will be used for
2317 logging wtmp style records instead of the regular T+ accounting
2320 wtmp records are generated into wtmpfilename. Since file locking is
2321 also used when writing to wtmpfilename, the usual provisos regarding
2322 NFS and locking (see accounting above) should be observed.
2324 To generate correct wtmp log records, the NAS needs to be configured
2327 aaa accounting exec stop-only tacacs+
2328 aaa accounting network stop-only tacacs+
2329 aaa accounting system start-stop tacacs+
2331 CANNED CONFIGURATIONS
2332 ---------------------
2334 Here are some canned configurations for getting demos started:
2336 1). A canned configuration for login authentication only. This allows
2337 user fred to login with password "abcdef". If the tacacs+ server dies,
2338 the enable secret will be accepted as a login password instead.
2344 # repeat as necessary for each user
2346 login = cleartext abcdef
2352 enable secret foobar
2353 ! use tacacs+. If server dies, use the enable secret password
2354 aaa authentication login default tacacs+ enable
2355 tacacs-server host <some host ip address>
2356 tacacs-server key <some key>
2358 2). A canned configuration for command authorization. This will allow
2359 user fred to login with password abcdef and to run the privileged
2360 (level 15) commands 'write terminal' and 'configure'. All other
2361 privileged commands will be denied.
2363 The "none" keyword in the NAS configuration line means that if the
2364 tacacs+ server dies, any command will be allowed.
2370 # repeat as necessary for each user
2372 login = cleartext abcdef
2385 ! all level 15 (privileged commands). If server dies, allow everything
2386 aaa authorization commands 15 tacacs+ none
2387 tacacs-server host <some host ip address>
2388 tacacs-server key <some key>
2390 3). Canned configuration for network access authorization. This config
2391 allows "fred" to login to line 1 with password abcdef (or to and to
2392 run ppp using chap authentication. The chap password is "lab".
2398 # repeat as necessary for each user
2400 login = cleartext abcdef
2401 chap = cleartext lab
2402 service = ppp protocol = ip {
2410 ! authenticate exec logins (if not autoselecting)
2411 aaa authentication login default tacacs+
2412 ! authorize network services via tacacs+
2413 aaa authorization network tacacs+
2414 ! use tacacs+ for authenticating ppp users
2415 aaa authentication ppp default tacacs+
2416 tacacs-server host <some host ip address>
2417 tacacs-server key <some key>
2419 ip address 1.0.0.1 255.0.0.0
2420 async default ip address 172.21.14.55
2422 async dynamic address
2423 async mode interactive
2424 ! use chap to authenticate ppp users
2425 ppp authentication chap
2427 ! need "modem inout" here and flow control if using a modem
2429 4). Canned configuration for ARAP.
2434 aaa authentication arap default guest tacacs+
2435 aaa authorization network tacacs+
2436 aaa accounting network start-stop tacacs+
2439 arap network <number> <name>
2442 appletalk cable-range <range>
2443 appletalk zone <zonename>
2445 tacacs-server host <host>
2446 tacacs-server key <key>
2450 modem answer-timeout 0
2453 autoselect during-login
2456 flowcontrol hardware
2463 arap = cleartext <arap secret>
2467 Authorization AV pairs
2468 ----------------------
2469 The following authorization AV pairs are supported by 10.3(3) onwards
2470 except where specifically noted.
2472 The following AV pairs specify which service is being authorized. They
2473 are typically accompanied by protocol AV pairs and other, additional
2474 pairs from the lists below.
2477 service=shell (for exec startup, and also for command authorizations)
2481 service=system (not used).
2484 Used for managing reverse telnet connections e.g.
2487 login = cleartext lab
2489 port#1 = nasname1/tty2
2490 port#2 = nasname2/tty5
2494 Requires IOS configuration
2496 aaa authorization reverse-access tacacs+
2498 See the IOS docs for more details.
2501 The lower layer of PPP, always brought up before IP, IPX, etc.
2505 Used with service=ppp and service=slip to indicate which
2506 protocol layer is being authorized.
2510 Used with service=ppp to indicate which protocol layer
2511 is being authorized.
2514 with service=ppp or service=arap
2520 Authorization of CCP. Compression Control Protocol). No other
2521 av-pairs associated with this.
2524 Authorization of CDP (Cisco Discovery Protocol). No other
2525 av-pairs associated with this.
2528 Authorization of multilink PPP. See 'max-links' and 'load-threshold'.
2531 For undefined/unsupported conditions. Should not occur under
2532 normal circumstances.
2535 If the value of cmd is NULL e.g. the AV pair is cmd=, then
2536 this is an authorization request for starting an exec.
2538 If cmd is non-null, this is a command authorization request,
2539 It contains the name of the command being authorized
2543 During command authorization, the name of the command is given
2544 by an accompanying "cmd=" AV pair, and each command argument
2545 is represented by a cmd-arg AV pair e.g. cmd-arg=archie.sura.net
2547 NOTE: 'cmd-arg' should never appear in a configuration file.
2548 It is used internally by the daemon to construct a string
2549 which is then matched against the regular expressions which appear
2550 in a cmd clause in the configuration file.
2553 For ARAP this contains an access-list number. For EXEC
2554 authorization it contains an access-class number, e.g. acl=2.
2555 which is applied to the line as the output access class equivalent
2556 to the configuration command
2561 An outbound access-class is the best way to restrict outgoing telnet
2562 connections. Note that a suitable access list (in this case,
2563 numbered 2) must be predefined on the NAS.
2566 This AV pair contains an IP or IPX input access list number
2567 for slip or PPP e.g. inacl=2. The access list itself must be
2568 pre-configured on the Cisco box. Per-user access lists do not
2569 work with ISDN interfaces unless you also configure a virtual
2570 interface. After 11.2(5.1)F, you can also use the name of a
2571 predefined named access list, instead of a number, for the
2572 value of this attribute.
2574 Note: For IPX, inacl is only valid after 11.2(4)F.
2576 inacl#<n> (PPP/IP, PPP/IPX, 11.2(4)F)
2577 This AV pair contains the definition of an input access list
2578 to be installed and applied to an interface for the duration
2579 of the current connection, e.g.
2581 inacl#1="permit ip any any precedence immediate"
2582 inacl#2="deny igrp 0.0.1.2 255.255.0.0 any"
2584 Attributes are sorted numerically before they are applied.
2585 For IP, standard OR extended access list syntax may be used,
2586 but it is an error to mix the two within a given access-list.
2588 For IPX, only extended access list syntax may be used.
2593 sho ipx access-lists
2598 outacl (PPP/IP, PPP/IPX)
2599 This AV pair contains an IP or IPX output access list number
2600 for SLIP. PPP/IP or PPP/IPX connections e.g. outacl=4. The
2601 access list itself must be pre-configured on the Cisco
2602 box. Per-user access lists do not work with ISDN interfaces
2603 unless you also configure a virtual interface. PPP/IPX is
2604 supported in 11.1 onwards only. After 11.2(5.1)F, you can also
2605 use the name of a predefined named access list, as well as a
2606 number, for the value of this attribute.
2609 outacl#<n> (PPP/IP, PPP/IPX, 11.2(4)F)
2610 This AV pair contains an output access list definition to be
2611 installed and applied to an interface for the duration of the
2612 current connection, e.g.
2614 outacl#1="permit ip any any precedence immediate"
2615 outacl#2="deny igrp 0.0.9.10 255.255.0.0 any"
2617 Attributes are sorted numerically before they are applied.
2618 For IP, standard OR extended access list syntax may be used,
2619 but it is an error to mix the two within a given access-list.
2621 For IPX, only extended access list syntax may be used.
2626 sho ipx access-lists
2632 The IP address the remote host should be assigned when a slip
2633 or PPP/IP connection is made e.g. addr=1.2.3.4
2635 routing (SLIP, PPP/IP)
2636 Equivalent to the /routing flag in slip and ppp commands. Can
2637 have as its value the string "true" or "false".
2639 timeout (11.0 onwards, ARAP, EXEC)
2640 Sets the time until an arap or exec session disconnects
2641 unconditionally (in minutes), e.g. timeout=60
2644 During exec startup, this specifies an autocommand, like the
2645 autocommand option to the username configuration command,
2646 e.g. autocmd="telnet foo.com"
2649 During exec startup, this specifies "noescape", like the
2650 noescape option to the username configuration command. Can
2651 have as its value the string "true" or "false",
2655 During exec startup, this specifies "nohangup", like the
2656 nohangup option to the username configuration command. Can
2657 have as its value the string "true" or "false",
2661 Specifies the current privilege level for command
2662 authorizations, a number from zero to 15 e.g. priv_lvl=5.
2664 Note: in 10.3 this attribute was priv_lvl i.e.
2665 it contained an underscore instead of a hyphen.
2668 An Appletalk zonelist for arap equivalent to the line
2669 configuration command "arap zonelist" e.g. zonelist=5
2671 addr-pool (11.0 onwards, PPP/IP, SLIP)
2672 This AV pair specifies the name of a local pool from which to
2673 get the IP address of the remote host.
2675 Note: addr-pool works in conjunction with local pooling. It
2676 specifies the name of a local pool (which needs to be
2677 pre-configured on the NAS). Use the ip-local pool command to
2678 declare local pools, e.g on the NAS:
2680 ip address-pool local
2681 ip local pool foo 1.0.0.1 1.0.0.10
2682 ip local pool baz 2.0.0.1 2.0.0.20
2684 then you can use Tacacs+ to return addr-pool=foo or
2685 addr-pool=baz to indicate which address pool you want to get
2686 this remote node's address from, e.g. on the daemon:
2689 service = ppp protocol = ip {
2694 route (11.1 onwards, PPP/IP, SLIP).
2695 This AV pair specifies a route to be applied to an interface.
2697 During network authorization, the "route" attribute may be
2698 used to specify a per-user static route, to be installed via
2701 The daemon side declaration is:
2703 service=ppp protocol=ip {
2704 route="<dst_addr> <mask> [ <gateway> ]"
2707 This indicates a temporary static route that is to be
2708 applied. "<dst_address>, <mask> and [<gateway>]" are expected
2709 to be in the usual dotted-decimal notation, with meanings the
2710 same as for the familiar "ip route" configuration command on a
2713 If gateway is omitted, the peer's address is taken to be the gateway.
2715 The route is expunged once the connection terminates.
2717 route#<n> (PPP/IP/IPX, 11.2(4)F)
2718 Same as the "route" attribute, except that these are valid for
2719 IPX as well as IP, and they are numbered, allowing multiple
2720 routes to be applied e.g.
2722 route#1="3.0.0.0 255.0.0.0 1.2.3.4"
2723 route#2="4.0.0.0 255.0.0.0"
2728 route#1="4C000000 ff000000 30.12.3.4"
2729 route#2="5C000000 ff000000 30.12.3.5"
2737 callback-rotary (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2738 The number of a rotary group (between 0 and 100 inclusive)
2739 to use for callback e.g. callback-rotary=34. Not valid for ISDN.
2741 callback-dialstring (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2742 sets the telephone number for a callback e.g.
2743 callback-dialstring=408-555-1212. Not valid for ISDN.
2745 callback-line (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2746 The number of a tty line to use for callback e.g.
2747 callback-line=4. Not valid for ISDN.
2749 nocallback-verify (11.1 onwards, valid for ARAP, EXEC)
2750 Indicates that no callback verification is required. The only
2751 valid value for this parameter is the digit one i.e.
2752 nocallback-verify=1. Not valid for ISDN.
2754 idletime (11.1 onwards, EXEC)
2755 Sets a value, in minutes, after which an IDLE session will be
2756 terminated. N.B. Does NOT work for PPP.
2758 tunnel-id (11.2 onwards, PPP/VPDN)
2759 This AV pair specifies the username that will be used to
2760 authenticate the tunnel over which the individual user MID
2761 will be projected. This is analogous to the "NAS name" in the
2762 "vpdn outgoing" command.
2764 ip-addresses (11.2 onwards, PPP/VPDN)
2765 This is a space separated list of possible IP addresses that
2766 can be used for the end-point of the tunnel.
2768 In 11.2(5.4)F, this attribute was extended as follows:
2770 1) comma (',') is also consider as a delimiter
2771 For example the avpair can now be written as
2773 ip-addresses = 172.21.9.26,172.21.9.15,172.21.9.4
2775 2) '/' is considered a priority delimiter. When you have a
2776 number of Home Gateway routers, it is desirable to consider some
2777 as the primary routers and some as backup routers.
2779 The '/' allow you to config the routers into priority groups,
2780 so that the NAS will try to forward the users to the high
2781 priority routers, before forwarding to the low priority one.
2783 For example in the following avpair:
2785 ip-addresses = "172.21.9.26 / 172.21.9.15 / 172.21.9.4"
2787 172.21.9.26 is considered to be priority 1
2788 172.21.9.15 is considered to be priority 2
2789 172.21.9.4 is considered to be priority 3
2791 The NAS will try to forward the users to 172.21.9.26, before
2792 trying 172.21.9.15. If the NAS can't forward users to
2793 172.21.9.26, it will try 172.21.9.15 next. If it fails with
2794 172.21.9.15, it will then try forwarding to 172.21.9.4.
2796 source-ip (PPP/VPDN, now deprecated, only existed in releases 11.2(1.4)
2797 thru 11.2(4.0.2)). This specifies a single ip address will be
2798 used as the source of all VPDN packets generated as part of
2799 the VPDN tunnel (see the equivalent source-ip keyword in the
2800 IOS vpdn outgoing command).
2802 nas-password (PPP/VPDN, 11.2(3.4)F, 11.2(4.0.2)F)
2803 During L2F tunnel authentication, nas-password specifies the password
2806 gw-password (PPP/VPDN, 11.2(3.4)F, 11.2(4.0.2)F)
2807 During L2F tunnel authentication, gw-password specifies the password
2808 for the home gateway.
2810 rte-ftr-in#<n> (PPP -- IP/IPX, 11.2(4)F)
2811 This AV pair specifies an input access list definition to be
2812 installed and applied to routing updates on the current
2813 interface, for the duration of the current connection.
2815 For IP, both standard and extended Cisco access list syntax is
2816 recognised, but it is an error to mix the two within a given
2819 For IPX, only Cisco extended access list syntax is legal.
2821 Attributes are sorted numerically before being applied. For
2822 IP, the first attribute must contain the name of a routing
2823 process and its identifier (except for rip, where no
2824 identifier is needed), e.g.
2826 rte-fltr-in#0="router igrp 60"
2827 rte-fltr-in#1="permit 0.0.3.4 255.255.0.0"
2828 rte-fltr-in#2="deny any"
2830 For IPX, no routing process is needed, e.g.
2832 rte-fltr-in#1="deny 3C01.0000.0000.0001"
2833 rte-fltr-in#2="deny 4C01.0000.0000.0002"
2837 show ip access-lists
2839 sho ipx access-lists
2844 Related IOS commands:
2846 router <routing process identifier>
2847 [no] distribute-list <list-name> in <interface>
2850 ipx input-network-filter <access-list-number>
2853 rte-ftr-out#<n> (PPP/IP, 11.2(4)F)
2854 This AV pair specifies an input access list definition to be
2855 installed and applied to routing updates on the current
2856 interface, for the duration of the current connection.
2858 For IP, both standard and extended Cisco access list syntax is
2859 recognised, but it is an error to mix the two within a given
2862 Attributes are sorted numerically before being applied. The
2863 first attribute must contain the name of a routing process and
2864 its identifier (except for rip, where no identifier is
2867 rte-fltr-out#0="router igrp 60"
2868 rte-fltr-out#3="permit 0.0.5.6 255.255.0.0"
2869 rte-fltr-out#4="permit any"
2871 For IPX, no routing process is specified, e.g.
2873 rte-fltr-out#1="deny 3C01.0000.0000.0001"
2874 rte-fltr-out#2="deny 4C01.0000.0000.0002"
2878 sho ipx access-lists
2880 show ip access-lists
2885 Related IOS commands:
2887 router <routing process identifier>
2888 [no] distribute-list <list-name> in <interface>
2891 ipx output-network-filter <access-list-number>
2894 sap#<n> (11.2(4)F PPP/IPX)
2895 This AV pair specifies static saps to be installed for the duration
2896 of a connection e.g.
2898 sap#1="4 CE1-LAB 1234.0000.0000.0001 451 4"
2899 sap#2="5 CE3-LAB 2345.0000.0000.0001 452 5"
2901 The syntax of static saps is the same as that used by the IOS
2909 Related IOS commands:
2913 route#<n> (PPP/IP/IPX, 11.2(4)F)
2915 Same as the "route" attribute, except that these are valid for
2916 IPX as well as IP, and they are numbered, allowing multiple
2917 routes to be applied e.g.
2919 route#1="3.0.0.0 255.0.0.0 1.2.3.4"
2920 route#2="4.0.0.0 255.0.0.0"
2925 route#1="4C000000 ff000000 30.12.3.4"
2926 route#2="5C000000 ff000000 30.12.3.5"
2935 sap-fltr-in#<n> (PPP/IPX, 11.2(4)F)
2936 This AV pair specifies an input sap filter access list
2937 definition to be installed and applied on the current
2938 interface, for the duration of the current connection.
2940 Only Cisco extended access list syntax is legal, e.g
2942 sap-fltr-in#1="deny 6C01.0000.0000.0001"
2943 sap-fltr-in#2="permit -1"
2945 Attributes are sorted numerically before being applied.
2947 sho ipx access-lists
2952 [no] ipx input-sap-filter <number>
2955 sap-fltr-out#<n> (PPP/IPX 11.2(4)F)
2956 This AV pair specifies an output sap filter access list
2957 definition to be installed and applied on the current
2958 interface, for the duration of the current connection.
2960 Only Cisco extended access list syntax is legal, e.g
2962 sap-fltr-out#1="deny 6C01.0000.0000.0001"
2963 sap-fltr-out#2="permit -1"
2965 Attributes are sorted numerically before being applied.
2967 sho ipx access-lists
2972 [no] ipx output-sap-filter <number>
2976 pool-def#<n> (PPP/IP, 11.2(4)F)
2977 This attribute is used to define ip address pools on the NAS.
2979 During IPCP address negotiation, if an ip pool name is
2980 specified for a user (see the addr-pool attribute), a check is
2981 made to see if the named pool is defined on the NAS. If it is,
2982 the pool is consulted for an ip address.
2984 If the required pool is not present on the NAS (either in the
2985 local config, or as a result of a previous download
2986 operation), then an authorization call to obtain it is
2987 attempted, using the special username:
2991 where <nas-name> is the configured name of the NAS.
2993 Note: This username can be changed using the IOS configuration
2996 aaa configuration config-name nas1-pools-definition.cisco.us
2998 The pool-def attribute is used to define ip address pools for
2999 the above authorization call e.g.
3002 login = cleartext lab
3003 service = ppp protocol = ip {
3009 service = ppp protocol = ip {
3010 pool-def#1 = "aaa 1.0.0.1 1.0.0.3"
3011 pool-def#2 = "bbb 2.0.0.1 2.0.0.10"
3012 pool-def#3 = "ccc 3.0.0.1 3.0.0.20"
3018 In the example above is a configuration file fragment for defining 3
3019 pools named "aaa", "bbb" and "ccc" on the NAS named "nas1".
3021 When the user "foo" refers to the pool named "bbb", if the
3022 pool "bbb" isn't defined, the NAS will attempt to download the
3023 definition contained in the "nas1-pools" entry.
3025 The other pools will also be defined at the same time (or they
3026 will be ignored if they are already defined).
3028 Since this procedure is only activated when an undefined pool
3029 is referenced, one way to redefine a pool once it has been
3030 downloaded is to manually delete the definition e.g. by
3031 logging into the NAS, enabling, and configuring:
3034 no ip local pool bbb
3037 When a pool is deleted, there is no interruption in service
3038 for any user who is currently using a pool address. If a pool
3039 is deleted and then subsequently redefined to include a pool
3040 address that was previously allocated, the new pool will pick
3041 up the allocated address and track it as expected.
3043 Since downloaded pools do not appear in the NAS configuration,
3044 any downloaded pool definitions automatically disappear
3045 whenever a NAS reboots. These pools are marked as "dynamic"
3046 when they appear in the output of the "show ip local pools"
3049 Since it is desirable not to have to manually delete pools to
3050 redefine them, the AV pair pool-timeout=<n> can be used to
3051 timeout any downloaded pool definitions. The timeout <n> is in
3054 The effect of the pool-timeout attribute is to start a timer
3055 when the pool definitions are downloaded. When the timer
3056 expires, the pools are deleted. The next reference to a
3057 deleted pool via will cause a re-fetch of the pool
3058 definitions. This allows pool changes to be made on the
3059 daemon and propagated to the NAS in a timely manner.
3064 sho ip local pool <pool-name>
3068 ip local pool <name> <start address> <end address>
3071 old-prompts (PPP/SLIP)
3072 This attribute is integrated into the following IOS images:
3074 11.2(7.4)P 11.2(7.4) 11.1(13.1) 11.(16.2) 11.1(13.1)AA
3075 11.1(13.1)CA 11.1(13.1)IA 11.2(8.0.1)F 11.0(16.2)BT)
3077 This attribute allows providers to make the prompts in T+
3078 appear identical to those of earlier systems (tacacs and
3079 xtacacs). This will allow administrators to upgrade from
3080 tacacs/xtacacs to T+ transparently to users.
3082 The difference between the prompts is as follows:
3084 In xtacacs, when the user types "slip" or "ppp" the system
3085 prompts for an address followed by a password, whereas T+
3086 prompts only for an address.
3088 In xtacacs, if the user types "slip host" or "ppp host", the
3089 system prompts for a password. In T+, there is no prompt.
3091 Using this attribute, T+ can be made to mimic the prompting
3092 behaviour of xtacacs, by configuring network authorization on
3093 IOS, and using the "old-prompts=true" attribute value pair for
3094 slip and ppp/ip, viz:
3097 global = cleartext foo
3102 default attribute = permit
3105 service = ppp protocol = ip {
3106 default attribute = permit
3111 i.e. the prompts are controlled by the addition of the
3112 "old-prompts=true" attribute.
3115 max-links (PPP/multilink - Multilink parameter; 11.3)
3116 This AV pair restricts the number of multilink bundle links
3117 that a user can have.
3119 The daemon side declaration is:
3121 service=ppp protocol=multilink {
3125 The range of <n> is [1-255].
3127 Related NAS commands:
3130 int virtual-template X
3131 multilink max-links <n>
3136 load-threshold (PPP/multilink - Multilink parameter; 11.3)
3137 This AV pair sets the load threshold at which an additional
3138 multilink link is added to the bundle (if load goes above) or
3139 deleted (if load goes below).
3141 The daemon side declaration is:
3143 service=ppp protocol=multilink {
3147 The range of <n> is [1-255].
3149 Related NAS commands:
3152 int virtual-template X
3153 multilink load-threshold <n>
3159 Reserved for future use:
3161 ppp-vj-slot-compression
3164 x25-addresses (PPP/VPDN)
3165 frame-relay (PPP/VPDN)