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 exist.
409 All forward references are not a problem, you can still make membership or
410 enlistment on the top of the file with the entity which will be defined on the
411 end of the configuration file.
413 CONFIGURING USER AUTHENTICATION
414 -------------------------------
416 User Authentication can be specified separately for PAP, ARAP, CHAP,
417 and normal logins. In addition, a user global authentication method
418 can be given that will be used if a per-protocol method is not
421 PAP, ARAP, CHAP, and global user authentication must be given in clear
424 The following assigns the user mary five different passwords for ARAP,
425 inbound and outbound CHAP, inbound PAP, outbound PAP, and normal login
429 arap = cleartext "arap password"
430 chap = cleartext "chap password"
431 pap = cleartext "inbound pap password"
432 opap = cleartext "outbound pap password"
433 login = des XQj4892fjk
437 The following assigns the user agnes a single password for all the
438 above types of login (except outbound PAP):
441 global = cleartext "Agnes global password"
444 NOTE: you cannot use a global user password for outbound PAP. This is
445 because outbound PAP is implemented by sending the password from the
446 daemon to the NAS. This is a security issue if the TACACS+ key is ever
449 There are 3 ways to authenticate a user for login.
451 1). You can include a DES (or cleartext) password for a user or for a
452 group that s/he is a member of, viz:
456 # this is lily's encrypted DES password. It overrides the admin
458 login = des XQkR21zMB0TDU
462 # fred is a member of group admin. He inherits the group's password
463 # as he does not have his one of his own.
468 # group admin has a cleartext password which all members share
469 # unless they have their own password defined
470 login = cleartext foobar
473 If no password is needed for this user, this can be accomplished with
474 the 'nopassword' option:
480 NOTE: The C program built from generate_passwd.c may be used to
481 hand-generate encrypted passwords, or they may be taken from a Unix
482 passwd (or shadow) file.
484 2). Authentication using passwd(5) files.
486 For selected users, you can perform DES authentication using existing
487 passwd(5) files instead of entering the password into the
488 configuration file directly (though using passwd(5) files is
489 noticeably less efficient for large files).
491 You can specify this behavior per-user, by naming a passwd(5) file in
492 the password declaration (instead of giving a DES password), as
496 # look in file /etc/tac_plus_passwords to authenticate this user
497 login = file /etc/tac_plus_passwords
500 3). Authentication using s/key.
502 If you have successfully built and linked in a suitable s/key library
503 and compiled tac_plus to use s/key, you can then specify that a user
504 be authenticated via s/key, as follows:
510 RECURSIVE PASSWORD LOOKUPS
511 ---------------------------
513 As stated earlier, authentication passwords are looked up recursively:
514 The daemon looks first to see if the user has her own password. If
515 not, it looks to see if she belongs to a group which has a
516 password. This process recurses through the hierarchy of groups (a
517 group can be a member of another group) until a password is found, or
518 there are no more groups.
520 CONFIGURING DEFAULT AUTHENTICATION
521 -----------------------------------
522 By default, an unrecognized user will be denied authentication (NOTE:
523 there is no way to authenticate someone with no username).
525 At the top level of the configuration file, you can set the default
526 authentication to use a passwd(5) file, viz:
528 default authentication = file /etc/passwd
530 The effect of this statement is that if a user does not appear in the
531 configuration file, the daemon will attempt to authenticate the user
532 using passwords from this file i.e. /etc/passwd in this example.
534 If you have passwd(5) files from previous versions of tacacs daemons,
535 this facility allows you to authenticate using the passwd(5) from
536 older versions of tacacs, while you migrate to using the new
539 CONFIGURING EXPIRY DATES
540 ------------------------
541 An entry of the form:
544 expires = "MMM DD YYYY"
545 password = cleartext "bite me"
548 will cause the user's passwords to become invalid, starting on the
549 expiry date. The only valid date format is e.g. "Jan 1 1980". Case is
552 A expiry warning message is sent to the user when she logs in,
553 starting at 14 days before the expiration date.
555 On expiry, the administrator must re-set the expiry date in the
556 configuration file in order to grant continued access. Expiry applies
557 to all password types except "file" passwords.
559 If passwd(5) files are being used for authentication, the "expires"
560 field in the configuration file is not consulted. Instead, the daemon
561 looks at the the "shell" field of the password file entry for a valid
564 If Solaris shadow password files are used for authentication, the
565 "expires" field in the configuration file is not consulted. The expiry
566 field from the shadow password file (if it exists) is used as the
569 CONFIGURING AUTHENTICATION ON THE NAS
570 -------------------------------------
572 On the NAS, to configure login authentication on all lines (including
573 vty and console lines)
576 aaa authentication login default tacacs+
578 NOTE: As soon as you issue this command, you will no longer be able to
579 create new logins to your NAS without a functioning tacacs+ daemon
580 appropriately configured with usernames and password, so make sure you
583 As a safety measure while setting up, we suggest you configure an
584 enable secret and make it the last resort authentication method, so
585 if your tacacs+ daemon fails to respond you will be able to use the
586 NAS enable password to login. To do this, configure:
589 aaa authentication login default tacacs+ enable
591 If all else fails, and you find yourself locked out of the NAS due to
592 a configuration problem, the section on "recovering from lost
593 passwords" on Cisco's CCO web page will help you dig your way out.
595 CONFIGURING ENABLE PASSWORDS
596 ----------------------------
598 The default privilege level for an ordinary user on the NAS is usually
599 1. When a user enables, she can reset this level to a value between 0
600 and 15 by using the NAS "enable" command. If she doesn't specify a
601 level, the default level she enables to is 15.
603 You can enable via tacacs+ e.g. by configuring on the NAS:
605 aaa authentication enable default tacacs+
607 then whenever you attempt to enable, an authentication request is sent
608 with the special username $enab<n>$ where <n> is the privilege level
609 you are attempting to enable to.
611 (Note: in order to be compatible with earlier versions of tacacs, when
612 the requested enable level is 15, the daemon will also try the
613 username $enable$ before trying username $enab15$).
615 For example, with the above declaration, in order to enable on the
616 NAS, you need a user declaration like this one, on the daemon:
619 login = cleartext "the enable password for level 15"
622 Note: Be aware that this does have the side effect that you now have a
623 user named $enab15$ who can then login to your NAS if she knows the
626 Here is a similar declaration allowing users to enable to level 4:
629 login = des bsoF4OivQCY8Q
632 CONFIGURING AUTHORIZATION
633 -------------------------
635 Authorization must be configured on both the NAS and the daemon to
636 operate correctly. By default, the NAS will allow everything until you
637 configure it to make authorization requests to the daemon.
639 On the daemon, the opposite is true: The daemon will, by default, deny
640 authorization of anything that isn't explicitly permitted.
642 Authorization allows the daemon to deny commands and services
643 outright, or to modify commands and services on a per-user
644 basis. Authorization on the daemon is divided into two separate parts:
645 commands and services.
650 Exec commands are those commands which are typed at a Cisco exec
651 prompt. When authorization is requested by the NAS, the entire command
652 is sent to the tac_plus daemon for authorization.
654 Command authorization is configured by specifying a list of
655 egrep-style regular expressions to match command arguments (see the
656 supplied man page, regexp.3, for a full description of regular
657 expressions) and an action which is "deny" or "permit".
659 The following configuration example permits user Fred to run the
662 telnet 131.108.13.<any number> and
663 telnet 128.<any number>.12.3 and
666 All other commands are denied (by default).
671 # permit specified telnets
672 permit 131\.108\.13\.[0-9]+
673 permit 128\.[0-9]+\.12\.3
676 # permit show commands
681 NOTE: If an argument list you specify contains spaces or tabs, you
682 must enclose it in double quotes.
684 The command and arguments which the user types gets matched to the
685 regular expressions you specify in the configuration file (in order of
686 appearance). The first successful match performs the associated
687 action (permit or deny). If there is no match, the command is denied
690 Conversely, the following configuration example can be used to deny
693 telnet 131.108.13.<any number>
695 and permit all other arguments, since the last line will match any
696 argument list. All other commands and services are permitted due to
697 the "default service = permit" clause.
699 Note: the default statement must be the first in the user clause
702 default service = permit
704 # allow all fred's telnet commands except to 131.108.13.*
705 deny 131\.108\.13\.[0-9]+
710 Note: Matches are not anchored, so "deny 131.108.13.[0-9]+" matches
711 anywhere in the command. To anchor the match, use ^ at the beginning
712 of the regular expression.
714 Note: When a command has multiple arguments, users may enter them in
715 many different permutations. It can be cumbersome to create regular
716 expressions which will reliably authorize commands under these
717 conditions, so administrators may wish to consider other methods of
718 performing authorization e.g. by configuring NAS-local privileged
719 enable levels on the NAS itself.
724 For command authorization, the Cisco NAS expands all commands to their
725 full names e.g. when you type "config t" on the NAS, this will be
726 expanded to "configuration terminal" before being sent to the daemon
727 so that you don't need to list all the possible contractions of a
730 CONFIGURING DEFAULT AUTHORIZATION
731 ---------------------------------
733 There are 3 places where defaults for authorization may be
734 configured. Unless specified to the contrary, the default is always to
737 1). To override the default denial of authorization for users who are
738 not explicitly listed in the configuration file, the ersatz user
739 DEFAULT, if defined, can be used for authorizing such users, viz:
741 default authentication = file /etc/passwd
744 service = ppp protocol = ip {
749 In this example, users who do not appear elsewhere will be
750 authenticated via the /etc/passwd file, and authorized by the contents
751 of the user = DEFAULT entry.
753 Note: For backward compatibility, the directive,
755 default authorization = permit
757 may still be specifed at the top level of the configuration file. This
758 overrides the default denial of authorization for users who are not
759 explicitly listed in the configuration file, permitting all
760 authorization requests for such users.
762 2). At the user level i.e. inside the braces of a user declaration,
763 the default for a user who doesn't have a service or command
764 explicitly authorized is to deny that service or command. The
765 following directive will permit the service or command by default
769 default service = permit
772 NOTE: This directive must appear first inside the user declaration.
774 3). At the service authorization level i.e. inside the braces of a
775 service declaration, arguments in an authorization request are
776 processed according to the algorithm described later. Some actions
777 when authorizing services (e.g. when matching attributes are not
778 found) depend on how the default is configured. The following
779 declaration changes the default from deny to permit for this user and
784 default attribute = permit
788 NOTE: This directive must appear before any others inside the service
791 NOTE: for command authorization (as opposed to service authorization
792 being discussed here), you specify deny .* or permit .* as the last
793 line of the regular expression matches to create default behavior.
795 AUTHORIZING EXEC STARTUP
796 -------------------------
798 If you authorize some exec commands, you implicitly agree to allow
799 that user to start an exec (it doesn't make sense to permit exec
800 commands if an exec can't be started to run those commands)
802 In addition to agreeing to allow an exec to start, you can supply some
803 parameters whenever an exec starts e.g. an autocommand, a dialback
804 string or a connection access list (acl).
806 In the example below, when an exec is started on the NAS, an acl of 4
807 will be returned to the NAS:
811 # this following line permits an exec to start and permits
812 # all commands and services by default
814 default service = permit
817 # When an exec is started, its connection access list will be 4.
818 # It also has an autocmd.
820 autocmd = "telnet foobar"
824 # allow all fred's telnet commands except telnet to 131.108.13.*
825 deny 131\.108\.13\.[0-9]+
830 NOTE: specifying an autocommand, or any other exec services, is part
831 of EXEC AUTHORIZATION. For it to work, you must also configure exec
832 authorization on your NAS e.g.
834 aaa authorization exec tacacs+
837 AUTHORIZING EXEC, SLIP, PPP and ARAP SERVICES
838 ----------------------------------------------
840 Authorizing exec, slip, PPP and arap services is done quite
841 differently from command authorization.
843 When authorizing these services, the NAS sends a request containing a
844 number of attribute-value (AV) pairs, each having the form
848 (Note: during debugging, you may see AV pairs whose separator
849 character is a "*" instead of a "=" sign. This is to signify that the
850 value in a pair is optional. An "=" sign indicates a mandatory
851 value. A "*" denotes an optional value).
853 e.g. a user starting ppp/ip using an address of 131.108.12.44 would
854 generate a request with the following AV pairs:
860 You can use the NAS debugging command
862 debug aaa authorization
864 to see what authorization AV pairs are being used by the NAS. Note: If
865 you are not on the router console, you will also need to issue a
866 'terminal monitor' command to see debug output.
868 THE AUTHORIZATION PROCESS
869 -------------------------
871 Authorizing a single session can result in multiple requests being
872 sent to the daemon. For example, in order to authorize a dialin ppp
873 user for IP, the following authorization requests will be made from
876 1). An initial authorization request to startup ppp from the exec,
877 using the AV pairs service=ppp, protocol=ip, will be made (Note: this
878 initial request will be omitted if you are autoselecting ppp, since
879 you won't know the username yet).
881 This request is really done to find the address for dumb PPP (or SLIP)
882 clients who can't do address negotiation. Instead, they expect you to
883 tell them what address to use before PPP starts up, via a text message
884 e.g. "Entering PPP. Your address is 1.2.3.4". They rely on parsing
885 this address from the message to know their address.
887 2). Next, an authorization request is made from the PPP subsystem to
888 see if ppp's LCP layer is authorized. LCP parameters can be set at
889 this time (e.g. callback). This request contains the AV pairs
890 service=ppp, protocol=lcp.
892 3). Next an authorization request to startup ppp's IPCP layer is made
893 using the AV pairs service=ppp, protocol=ipcp. Any parameters returned
894 by the daemon are cached.
896 4). Next, during PPP's address negotiation phase, each time the remote
897 peer requests a specific address, if that address isn't in the cache
898 obtained in step 3, a new authorization request is made to see if the
899 peers requested address is allowable. This step can be repeated
900 multiple times until both sides agree on the remote peer's address or
901 until the NAS (or client) decide they're never going to agree and they
902 shut down PPP instead.
904 As you can see from the above, a program which plans to handle
905 authorization must be able to handle a variety of requests and respond
908 AUTHORIZATION RELIES ON AUTHENTICATION
909 --------------------------------------
911 Since we pretty much rely on having a username in authorization
912 requests to decide which addresses etc. to hand out, it is important
913 to know where the username for a PPP user comes from. There are
914 generally 2 possible sources
916 1). You force the user to authenticate by making her login to the exec
917 and you use that login name in authorization requests. This username
918 isn't propagated to PPP by default. To have this happen, you generally
919 need to configure the "if-needed" method, e.g.
921 aaa authentication login default tacacs+
922 aaa authentication ppp default if-needed
925 2). Alternatively, you can run an authentication protocol, PAP or CHAP
926 (CHAP is much preferred), to identify the user. You don't need an
927 explicit login step if you do this (so it's the only possibility if
928 you are using autoselect). This authentication gets done before you
929 see the first LCP authorization request of course. Typically you
930 configure this by doing:
932 aaa authentication ppp default tacacs+
934 ppp authentication chap
936 If you omit either of these authentication schemes, you will start to
937 see authorization requests in which the username is missing.
939 CONFIGURING SERVICE AUTHORIZATION
940 ---------------------------------
942 A list of AV pairs is placed in the daemon's configuration file in
943 order to authorize services. The daemon compares each NAS AV pair to
944 its configured AV pairs and either allows or denies the service. If
945 the service is allowed, the daemon may add, change or delete AV pairs
946 before returning them to the NAS, thereby restricting what the user is
949 The complete algorithm by which the daemon processes its configured
950 AV pairs against the list the NAS sends, is given below.
952 The Authorization Algorithm
953 ---------------------------
955 Find the user (or group) entry for this service (and protocol), then
956 for each AV pair sent from the NAS:
958 If the AV pair from the NAS is mandatory:
960 a). look for an exact attribute,value match in the user's
961 mandatory list. If found, add the AV pair to the output.
963 b). If an exact match doesn't exist, look in the user's
964 optional list for the first attribute match. If found, add the
965 NAS AV pair to the output.
967 c). If no attribute match exists, deny the command if the
968 default is to deny, or,
970 d). If the default is permit, add the NAS AV pair to the
973 If the AV pair from the NAS is optional:
975 e). look for an exact attribute,value match in the user's
976 mandatory list. If found, add DAEMON's AV pair to output.
978 f). If not found, look for the first attribute match in the
979 user's mandatory list. If found, add DAEMONS's AV pair to output.
981 g). If no mandatory match exists, look for an exact
982 attribute,value pair match among the daemon's optional AV
983 pairs. If found add the DAEMON's matching AV pair to the
986 h). If no exact match exists, locate the first attribute match
987 among the daemon's optional AV pairs. If found add the
988 DAEMON's matching AV pair to the output.
990 i). If no match is found, delete the AV pair if the default is
993 j). If the default is permit add the NAS AV pair to the output.
995 k). After all AV pairs have been processed, for each mandatory
996 DAEMON AV pair, if there is no attribute match already in the
997 output list, add the AV pair (but add only ONE AV pair for each
998 mandatory attribute).
1000 RECURSIVE AUTHORIZATION
1001 -----------------------
1003 Remember that authorization is also recursive over groups, in the same
1004 way that password lookups are recursive. Thus, if you place a user in
1005 a group, the daemon will look in the group for authorization
1006 parameters if it cannot find them in the user declaration.
1011 key = "your key here"
1014 login = des mEX027bHtzTlQ
1015 name = "Fred Flintstone"
1016 member = administrators
1017 expires = "May 23 2005"
1018 arap = cleartext "Fred's arap secret"
1019 chap = cleartext "Fred's chap secret"
1022 # When Fred starts an exec, his connection access list is 5
1025 # We require this autocmd to be done at startup
1026 autocmd = "telnet foo"
1029 # All commands except show system are denied for Fred
1032 # Fred can run the following show command
1038 service = ppp protocol = ip {
1039 # Fred can run ip over ppp only if he uses one
1040 # of the following mandatory addresses. If he supplies no
1041 # address, the first one here will be mandated
1048 # Fred's mandatory input access list number is 101
1051 # We will suggest an output access list of 102, but the NAS may
1052 # choose to ignore or override it
1059 # Fred can run slip. When he does, he will have to use
1060 # these mandatory access lists
1069 # Wilma has no password of her own, but she's a group member so
1070 # she'll use the group password if there is one. Same for her
1071 # password expiry date
1078 # group members who don't have their own login password will be looked
1081 login = file /etc/passwd
1083 # group members who have no expiry date set will use this one
1085 expires = "Jan 1 1997"
1089 CONFIGURATION RESPECTING NAS HOST OF THE USER
1090 ---------------------------------------------
1092 Sometimes you would want to modify the configuration file according to the
1093 source NAS where the user is being authenticated/authorized. For example if you
1094 are big ISP you want to permit administrator of company X to be able to monitor
1095 status of the links on NAS in company X but, of course, she should be able to
1096 monitor any other links on any other NAS of the same ISP. As all the NASes are
1097 authorized from the same Daemon, it seems as a problem. (You can workaround it
1098 by using custom authorization program - see "USING PROGRAMS TO DO
1099 AUTHORIZATION" section below - but it is not nice solution.)
1101 For this purposes there exists another entity 'host':
1108 As you can see you may use either IP address or DNS name. Anyway, we strongly
1109 recommend to always use only IP addresses - DNS subsystem may fail or it may be
1110 forged by the enemy.
1112 You have two methods of utilizing the differences between NASes:
1114 1) Current user is always automatically enlisted (=given membership to) to its
1115 current NAS host. This looks weird as only groups can have members but this
1116 is the only exception to this rule, current NAS host can really have a
1119 ( user "current_user" | user DEFAULT )
1121 +-- host "current_NAS_IP_address"
1125 +-- host "current_NAS_hostname"
1131 Each link only exists in the case it there exist both its peers, of course.
1132 user/group DEFAULT is written here only for the completeness of the chart.
1133 DEFAULT is discussed elsewhere in this documentation.
1135 According to the shown ordering, attributes/values in the host of current
1136 NAS identified by its IP address has _higher_ precence over the attributes
1137 in the current NAS identified by its (reverse-resolved) hostname.
1139 According to this auto-connections, you can for example permit some command
1140 to ALL the users on such NAS:
1143 login = cleartext LLLL
1145 host = machine.A.company {
1151 In this configuration file ALL the valid users can do "write terminal" when
1152 logged in on NAS "machine.A.company".
1154 2) Sometimes you need to do the authorization specific only to some users on
1155 some NASes. For example to permit "write terminal" ONLY to user fred
1156 connected to NAS "machine.A.company". That means that you want to forbid it
1157 to user fred on any other NAS and yuo also want to forbid it to all the
1158 other users on NAS "machine.A.company". (Line "authorization = recursive" is
1159 required but read the following section "FULL RECURSIVITY" to know all its
1162 authorization = recursive
1164 login = cleartext LLLL
1166 host = machine.A.company {
1174 This file has the same effect as:
1176 authorization = recursive
1178 login = cleartext LLLL
1179 when = host machine.A.company {
1185 host = machine.A.company {
1188 You can see the (nested) command "when" can limit the scope of existence of
1189 its contents. Unfortunately you cannot use "when" to limit any items, just
1195 cmd arguments (to limit specific "permit"/"deny" lines)
1196 service (or incl. "protocol" specification)
1197 service AV pairs (to limit specific "attr=value" lines)
1198 when (enabling pure nesting of "when" blocks)
1200 Full flexibility to limit any contents may be done in future (needs complete
1201 cfgfile.c rewrite) but currently it is not supported. Fortunately you can
1202 get the same behaviour by appropriate usage of "member" keyword - all the
1203 attributes to be conditioned are put into separate group and you limit only
1204 the "member" keyword to such group.
1206 "when" command has the form "when = CONDITION { BLOCK }", CONDITION can be:
1208 user USR i.e. that current user is "USR")
1209 host HOSTNAME i.e. that current user is on NAS "HOSTNAME")
1210 group GRP i.e. current user belongs to the group "GRP",
1211 All possible "when" conditions to reach such belonging
1212 have to be successfuly met to make this condition successful.
1213 Realize that "member" can be limited by "when" keyword.
1214 CONDITION and CONDITION and CONDITION ...
1215 CONDITION or CONDITION or CONDITION ...
1219 You can see that you CANNOT use for example "user A and user B or user C",
1220 such condition would have ambiguous precedence of operators, you must
1221 explicitly write: ( user A and user B ) or user C
1222 or: user A and ( user B or user C )
1224 Both parentheses have to be written as separate words, NOT "(user A)"
1225 but "( user A )" instead.
1226 (Proper solution would also need the complete cfgfile.c rewrite.)
1228 "not" operator has the highest precendence, so: not user A or user B
1229 has the same meaning as: ( not user A ) or user B
1231 Sometimes the "when" condition is so-called unresolvable. Example:
1240 It is looping, when we would be the member of GRP, we would be really the
1241 member of GRP but otherwise sould wouldn't be the member of GRP. Weird?
1242 Yes, such case is considered as configuration bug, it is reported as:
1244 Unable to resolve expression from line 243, some looping occured
1246 Generally such unresolvable conditional expression is considered as UNKNOWN
1247 and the "when" keyword is then evaluated as "false" (=skip it's block).
1248 This MAY produce unwanted privilege access (if you were conditionally
1249 forbidding some privileges) so always watch out all the error messages in
1250 logs! (You should generally do default deny and specifically only "permit"
1251 all the privileges so the unintentional unresolvable expressions shouldn't
1257 We have written in the previous examples line:
1259 authorization = recursive
1261 This changes some behaviour of Daemon:
1263 1) Looping of memberships: By default any looped memberships are reported as
1264 error with message: recursively defined groups: ...
1266 After "authorization = recursive" any looping is silently accepted as it
1267 would be sometimes hard to prevent it in some complex configurations.
1268 Searching is done in normal Depth-First Search, but traversion is
1269 backtracked one step when the entity was already visited. Simply it will
1270 work 'magically', just safely ignore the fact.
1272 2) "default service = default" is supported only with:
1273 authorization = recursive
1274 This isn't any real change, just some formality. In fact each entity block
1275 has "default service = default" in effect as default (in the case you don't
1276 write any "default service =" assign).
1278 "authorization = recursive" is enforced here due to the change of Daemon
1279 behaviour: In non-recursive (old) case the Daemon assumes "deny .*" as the
1280 last line of "cmd" block. This makes proper NAS-host based permissions
1281 impossible. In "authorization = recursive" mode it requires appropriate
1282 "permit" or "deny" line to apply - otherwise the Depth-First Search through
1283 the entities will continue to find another applicable "cmd" block (toplevel
1284 "default authorization" may get into effect as the last resort).
1286 "default service" keyword takes then another meaning: In non-recursive mode
1287 it will mean "if the command wasn't found". In fully-recursive mode it will
1288 mean "if any cmd block didn't decide".
1290 Please keep in mind that "service =" (with its possible "protocol =" mate)
1291 has always the same behaviour, nothing is changed with "authorization =
1292 recursive" enabled. Its functionality is already a bit complex (with AV
1293 pairs get erased, which added, which copied, which are optional from NAS,
1294 which optional from Daemon, whether to do default permit or deny etc.).
1295 Fortunately we didn't found that there would be needed some extended
1296 'recursiveness' functionality of "service" for application of NAS-host based
1299 3) "host" entities are not recursive at all (=its attributes aren't looked up
1300 in its parent groups) without "authorization = recursive". This isn't any
1301 much change as in the previous versions of Daemon "host" entity was either
1302 completely unsupported or it was supported only with the only one attribute:
1304 "key": Attribute defines different protocol key (instead of the specified
1305 toplevel one) for the specified host. Its use is recommended to
1306 improve overall network security (by using unique key for each NAS).
1308 USING PROGRAMS TO DO AUTHORIZATION
1309 ----------------------------------
1311 There are some limitations to the authorization that can be done using
1312 a configuration file. The main ones are that you're constrained by the
1313 algorithm the daemon uses, and that the configuration is basically
1314 static, so if you're trying to use it to allocate dynamic things (such
1315 as addresses from a pool) that vary over time, you need another
1318 One solution is to arrange for the daemon to call your own
1319 user-supplied programs to control authorization. These "callouts"
1320 permit almost complete control over authorization, allowing you to
1321 read all the fields in the authorization packet sent by the NAS
1322 including all its AV pairs, and to set authorization status and send a
1323 new set of AV pairs to the NAS in response.
1325 USING AV PAIRS FOR AUTHORIZATION
1326 --------------------------------
1328 During authorization, the NAS sends an authorization request packet
1329 containing various fields of interest and a set of AV pairs (see the
1330 tacacs+ protocol specification for a list of fields and pairs).
1332 Fields from the authorization packet can be supplied to the programs
1333 you call on their command line, by using the appropriate dollar
1334 variables in the configuration file (see below).
1336 AV pairs from the authorization packet are fed to the program's
1337 standard input, one per line. The program is expected to process the
1338 AV pairs and write them to its standard output, one per line. What
1339 happens then is determined by the exit status of the program.
1341 NOTE: AV pairs are text strings with the format
1342 attribute=value. Unlike the configuration file which allows spaces
1343 when specifying AV pairs, there should be no spaces surrounding the
1344 "=" sign when using the programmatic interface.
1346 CALLING SCRIPTS BEFORE AUTHORIZATION
1347 ------------------------------------
1349 You can specify a per-user program to be called before any other
1350 attempt to authorize is made by using a "before" clause e.g.
1353 before authorization "/usr/bin/pre_authorize $user $port $address"
1356 The AV pairs sent from the NAS will be supplied to this program's
1357 standard input, one pair per line.
1359 Fields from the initiating authorization packet which the NAS sends to
1360 the daemon can also be passed to the program by using dollar variables
1361 in the command line. A complete list of available variables is as
1362 follows (consult the API specification for more details).
1367 address -- Nac address (remote user location)
1368 priv -- privilege level (a digit, 0 to 15)
1369 method -- (a digit, 1 to 4)
1370 type -- (a digit, 1 to 4)
1371 service -- (a digit, 1 to 7)
1372 status -- (pass, fail, error, unknown)
1374 Unrecognized variables will appear as the string "unknown".
1376 If the program returns a status of 0, authorization is unconditionally
1377 permitted. No further processing is done on this request and no AV
1378 pairs are returned to the NAS.
1380 If the program returns a status of 1, authorization is unconditionally
1381 denied. No further processing is done on this request and no AV pairs
1382 are returned to the NAS.
1384 If the program returns a status of 2, authorization is permitted. The
1385 program is expected to modify the AV pairs that it receives on its
1386 standard input (or to create entirely new ones) and to write them, one
1387 per line, to its standard output. The new AV pairs will be sent to the
1388 NAS with a status of AUTHOR_STATUS_PASS_REPL. No further processing
1389 takes place on this request.
1391 If the program returns a status of 3, authorization is denied, but all
1392 attributes returned by the program via stdout are returned to the
1393 NAS. Also, whatever the program returns on stderr is placed into the
1394 server-msg field and returned to the NAS as well.
1396 Any other status value returned from the program will cause an error
1397 to be returned to the NAS.
1399 Note that a status of 2 is not acceptable when doing command
1402 CALLING PROGRAMS AFTER AUTHORIZATION
1403 ------------------------------------
1405 You can specify a per-user program to be called after authorization
1406 processing has been carried out by the daemon (but before the
1407 authorization status and AV pairs have been transmitted to the NAS).
1409 The program can optionally modify the AV pairs being sent back to the
1410 NAS and change the authorization status if required.
1413 # call /usr/bin/post_authorize passing it the username, port
1414 # and current authorization status.
1415 after authorization "/usr/bin/post_authorize $user $port $status"
1418 The AV pairs resulting from the authorization algorithm that the
1419 daemon proposes to return to the NAS, are supplied to the program on
1420 standard input, one AV pair per line, so they can be modified if
1423 Fields from the incoming authorization packet which the NAS sent to
1424 the daemon can also be passed to the program on its command line by
1425 specifying dollar variables in the command line (see previous
1428 The program is expected to process the AV pairs and write them to its
1429 standard output, one per line. What happens then is determined by the
1430 exit status of the program:
1432 If the program returns a status of 0, authorization continues as if
1433 the program had never been called. Use this if e.g. you just want a
1434 program to send mail when an authorization occurs, without otherwise
1435 affecting normal authorization.
1437 If the program returns a status of 1, authorization is unconditionally
1438 denied. No AV pairs are returned to the NAS. No further authorization
1439 processing occurs on this request.
1441 If the program returns a status of 2, authorization is permitted and
1442 any AV pairs returned from the program on its standard output are sent
1443 to the NAS in place of any AV pairs that the daemon may have
1446 Any other value will cause an error to be returned the the NAS by the
1449 WARNINGS AND CAUTIONS
1450 ---------------------
1452 Customers attempting to write authorization scripts will find the NAS
1453 debugging command "debug aaa authorization" invaluable.
1455 Pre and post authorization programs are invoked by handing the command
1456 line to the Bourne shell. On many Unix systems, if the shell doesn't
1457 find the specified program it returns a status of one, which denies
1458 authorization. However, at least one Unix system (BSDI) returns a
1459 status code of 2 under these circumstances, which will permit
1460 authorization, and probably isn't what you intended.
1462 Note also that if your program hangs, the authorization will time out
1463 and return an error on the NAS, and you'll tie up a process slot on
1464 the daemon host, eventually running out of resources. There is no
1465 special code to detect this in the daemon.
1467 Unless you make special arrangements, the daemon will run as root and
1468 hence the programs it invokes will also run as root, which is a
1469 security weakness. It is strongly recommended that you use absolute
1470 pathnames when specifying programs to execute, and that you use the
1471 Makefile options TAC_PLUS_USERID and TAC_PLUS_GROUPID so that the
1472 daemon is not running as root when calling these programs,
1474 The daemon communicates with pre and post authorization programs over
1475 a pair of pipes. Programs using the standard i/o library will use full
1476 buffering in these circumstances. This shouldn't be a problem for most
1477 programs, since they'll read AV pairs till they see end of file on
1478 input, and they'll flush all output when they exit.
1480 Note that when avpairs containing spaces are listed in the
1481 configuration file, you need to enclose them in double quotes so that
1482 they are parsed correctly. Avpairs which are returned via standard
1483 output do not need delimiters and so should not be enclosed in double
1486 CONFIGURING AUTHORIZATION ON THE NAS
1487 ------------------------------------
1489 If authorization is not explicitly configured on the NAS, no
1490 authorization takes place i.e. effectively, everything is
1491 permitted. Note that this is the converse of what happens on the
1492 daemon, where anything not explicitly permitted is denied by default.
1494 To configure command authorization on the NAS, issue the following NAS
1495 configuration commands:
1497 aaa authorization commands 1 tacacs+
1498 aaa authorization commands 15 tacacs+
1501 This will make the NAS send tacacs+ requests for all level 1 (ordinary
1502 user) and level 15 (privileged level) commands on all lines/interfaces.
1504 NOTE: As soon as you configure the above on your NAS, you will only be
1505 permitted to execute NAS commands which are permitted by your tacacs+
1506 daemon. So make sure you have configured, on the daemon, an
1507 authenticated user who is authorized to run commands, or you will be
1508 unable to do much on the NAS after turning on authorization.
1510 Alternatively, or in addition, you may also want to configure the
1513 aaa authorization commands 1 tacacs+ if-authenticated
1515 This will use tacacs+ authorization for level 1 (user-level commands)
1516 but if problems arise, you can just switch off the tacacs+ server and
1517 authorization will then be granted to anyone who is authenticated.
1519 The following daemon configuration should be sufficient to ensure that
1520 you can always login as username "admin" (with a suitable password)
1521 and run any command as that user:
1524 default service = permit
1525 login = des kppPfHq/j6gXs
1532 There is only one configurable accounting parameter -- the accounting
1533 file name. All accounting records are written, as text, to this
1534 filename. The filename is configured as follows at the top-level of
1535 the configuration file:
1537 accounting file = <filename>
1539 Since accounting requests occur (and are serviced) asynchronously, it
1540 is necessary to lock the accounting file so that two writers don't
1541 simultaneously update it. The daemon uses the fcntl call to do this
1542 locking, so it is recommended that the accounting file reside on a
1543 local filesystem. Although fcntl locking over NFS is supported on some
1544 Unix implementations, it is notoriously unreliable. Even if your
1545 implementation is reliable, locking is likely to be extremely
1546 inefficient over NFS.
1551 To get accounting records equivalent to previous versions of tacacs,
1552 the following is sufficient. "Stop" records contain elapsed time for
1553 connections and exec sessions.
1555 aaa accounting network stop-only tacacs+
1556 aaa accounting exec stop-only tacacs+
1559 CONFIGURING CALLBACK WITH TACACS+
1560 ---------------------------------
1562 Note: Callback is available only in IOS 11.1 and later, and can only
1563 be controlled via Tacacs+ for ASYNC lines. ISDN callback can be
1564 configured on the NAS but cannot be controlled via AAA.
1566 Here is an example of AAA configuration (with exec and network
1567 accounting enabled):
1572 tacacs-server host XX.XX.XX.XX
1573 tacacs-server key fookey
1574 aaa accounting exec wait-start tacacs+
1575 aaa accounting network wait-start tacacs+
1577 ! Example of AAA configuration for Exec:
1578 aaa authentication login execcheck tacacs+
1579 aaa authorization network tacacs+
1580 service exec-callback
1583 login authentication execcheck
1585 ! Example of AAA configuration for ARAP:
1586 aaa authentication arap arapcheck tacacs+
1587 aaa authorization network tacacs+
1591 arap authentication arapcheck
1593 ! Example of AAA-specific configuration for PPP callback:
1595 aaa authentication ppp pppcheck tacacs+
1596 aaa authorization network tacacs+
1599 ppp authentication chap pppcheck
1602 Daemon configuration:
1604 Example of remote TACACS+ server CONFIG file entry for username `foobar':
1607 arap = cleartext AAAA
1608 login = cleartext LLLL
1609 chap = cleartext CCCC
1610 pap = cleartext PPPP
1611 opap = cleartext OOOO
1612 service = ppp protocol = lcp {
1613 callback-dialstring=123456
1616 callback-dialstring=2345678
1619 callback-dialstring=3456789
1628 DEBUGGING CONFIGURATION FILES
1629 -----------------------------
1631 When creating configuration files, it is convenient to check their
1632 syntax using the -P flag to tac_plus e.g.
1634 tac_plus -P -C <config file name>
1636 will syntax check the configuration file and print any error messages
1639 DEBUGGING A RUNNING SERVER
1640 --------------------------
1642 There is a myriad of debugging values that can be used in conjunction
1643 with the -d flag to produce debugging output in /var/log/tac_plus.log.
1645 For example, starting the daemon with
1647 tac_plus -C CONFIG -d 16
1649 will put authentication debugging into /var/log/tac_plus.log. You can
1650 view this information by using the tail command.
1652 tail -f /var/log/tac_plus.log
1654 See the man page for more information.
1656 CHANGING CONFIGURATIONS
1657 -----------------------
1659 To change a configuration file, you must edit the configuration file
1660 and then send the daemon a SIGUSR1. This will cause it to reinitialize
1661 itself and re-read the configuration file.
1663 On startup, tac_plus creates the file /var/run/tac_plus.pid , if possible,
1664 containing its process id. If you invoke the daemon so that it listens
1665 on a non-standard port, the file created is /var/run/tac_plus.pid.<port>
1666 instead, where <port> is the port number the daemon is listening on.
1668 Assuming you are listening on the default port 49, something like the
1669 following should work:
1671 # kill -USR1 `cat /var/run/tac_plus.pid`
1673 It's a good idea to check that the daemon is still running after
1674 sending it a SIGUSR1, since a syntactically incorrect configuration
1675 file will cause the daemon to die.
1677 NOTE: The perl script generate_passwd.pl may be used to hand-generate
1678 encrypted passwords, or they may be taken from a Unix passwd file.
1680 FREQUENTLY ASKED QUESTIONS
1681 --------------------------
1682 Q). Does T+ required a working DNS?
1684 A). As distributed, whenever a START packet arrive, the daemon makes a
1685 call to getpeername to find out the name of the requestor. Depending
1686 entirely on how your Unix host is set up, this may make DNS
1687 queries. If this is a problem, comment out the code in tac_plus.c
1688 which does this, and just use ip addresses instead of host names.
1690 Q). Is the "name" field used for anything
1692 A). No. It's purely for documentation. I had once thought it might be
1693 useful when outputting error messages, and that you might need the
1694 information if you converted a passwd(5) style file, but no use is
1695 currently made of the field.
1697 Q). Why do I get PPP authorization failures because of "no username in
1698 request" when I've already logged in and authenticated?
1700 A). With "aaa authentication PPP default tacacs+", the ppp
1701 authentication overrides the earlier login authentication. If the ppp
1702 authentication fails, the username ends up blank. Changing the config
1703 to "aaa authentication ppp default if-needed tacacs+" fixes this
1706 Q). I'm sure I configured it correctly, but accounting still doesn't
1709 A). You will find that although you can configure accounting in 10.3,
1710 and it outputs debug messages, it doesn't send any accounting
1711 packets. This is because Accounting only works from 11.0 onwards.
1713 Q). Does TACACS+ use a database instead of a flat (/etc/passwd like)
1714 file to decrease search times, say if we are talking about a large
1715 database of 40,000 users?
1717 A). The TACACS+ authentication database is held internally as a hash
1718 table. This makes lookup times fast and fairly linear, at the expense
1719 of making the server use potentially large amounts of memory space.
1720 NOTE: If you specify that the server uses passwd(5) files for
1721 authentication, then you don't get this speed benefit, but you save
1724 If you're willing to write the code, it should be a relatively simple
1725 matter to interface the code to a database scheme e.g. unix dbm files,
1726 or some proprietary database package, if you wish.
1728 Q). Is there any way to avoid having clear text versions of the
1729 ARAP and CHAP secrets in the configuration file?
1731 CHAP and ARAP require that the server knows the cleartext password (or
1732 equivalently, something from which the server can generate the
1733 cleartext password). Note that this is part of the definition of CHAP
1734 and ARAP, not just the whim of some Cisco engineer who drank too much
1735 coffee late one night.
1737 If we encrypted the CHAP and ARAP passwords in the database, then we'd
1738 need to keep a key around so that the server can decrypt them when
1739 CHAP or ARAP needs them. So this only ends up being a slight
1740 obfuscation and not much more secure than the original scheme.
1742 In extended TACACS, the CHAP and ARAP secrets were separated from the
1743 password file because the password file may be a system password file
1744 and hence world readable. But with TACACS+'s native database, there
1745 is no such requirement, so we think the best solution is to
1746 read-protect the files. Note that this is the same problem that a
1747 kerberos server has. If your security is compromised on the kerberos
1748 server, then your database is wide open. Kerberos does encrypt the
1749 database, but if you want your server to automatically restart, then
1750 you end up having to "kstash" the key in a file anyway and you're back
1751 to the same security problem.
1753 So storing the cleartext password on the security server is really an
1754 absolute requirement of the CHAP and ARAP protocols, not something
1757 We could have chosen a scheme where the NAS sends the challenge
1758 information to the TACACS+ daemon and the daemon uses the cleartext
1759 password to generate the response and returns that, but that means
1760 that we must include specific protocol knowledge into the protocol for
1761 both ARAP and CHAP and we would have to update the protocol every time
1762 a new authentication protocol is added. Hence we decided to go with
1763 the SENDPASS mechanism.
1765 Note that the above doesn't apply to PAP. You can keep an inbound PAP
1766 password des-encrypted, since all you need to do with it is verify
1767 that the password the principal gave you is correct.
1769 Q). How is the typical login authentication sequence done?
1771 A). NAS sends START packet to daemon
1772 Daemon send GETUSER containing login prompt to NAS
1773 NAS prompts user for username
1774 NAS sends pkt to daemon
1775 Daemon sends GETPASS containing password prompt to the NAS
1776 NAS prompts user for password
1777 NAS sends pkt to daemon
1778 Daemon sends accept, reject or error to NAS
1781 Q). Is there a GUI for the configuration file?
1782 A). No. Use your favourite text editor.
1785 Q). What does "default service = permit" really do?
1787 A). When a request comes in to authorize exec startup, or ppp (with
1788 protocol lcp, ip, ipx), or slip, or arap or a specific command, the
1789 daemon looks for a matching declarations for the user (or groups the
1790 user is a member of).
1792 For exec startup, it looks for a "service=exec" OR any command
1795 For ppp, it looks for a "service=ppp" and "protocol=(one of lcp, ip,
1798 For slip there must be a "service=slip" and for arap a "service=arap"
1801 For specific commands, there must be a matching cmd=<cmdname>.
1803 If these aren't found, authorization will fail, *unless* you say
1804 "default service = permit".
1806 Q). How do I make PAP work?
1808 A). Avoid using PAP if possible since it's not very secure. If you
1809 *must* use it, PAP passwords may be specified along with arap and chap
1810 passwords for each user. Note that the details of this changed in
1811 version 3.0 and onwards.
1813 For outbound PAP, where you are forced to send a password to the
1814 remote host to identify yourself, there is now a separate "opap"
1817 opap = cleartext OOOO
1819 You use this to set the outbound PAP password. It must be a cleartext
1822 NOTE: It is very bad practice to use an outbound PAP password that is
1823 the same as any of your inbound passwords. For this reason, a "global"
1824 password does not apply to outbound PAP, only to inbound PAP,
1825 bidirectional CHAP and ARAP.
1827 Before 3.0, PAP logins were treated like ordinary user logins, so you
1828 needed to declare a user in the Daemon configuration file whose name
1829 was typically the remote hostname (or user), with a login password, in
1830 order to process the PAP request.
1832 Q). How can I deny some one from telneting from a commserver by ip
1833 address only. i.e. when command is 10.0.1.6 rather than telnet
1836 A). The best way to restrict telnet access is by applying an outbound
1837 access list via the access class command (or equivalently, via the
1838 "acl" avpair). The NAS configuration command "access-class <n> out"
1839 for example applies a pre-defined standard IP access list (where n is
1840 a number from 1 through 99) that governs telnet access from a NAS.
1842 E.g. the following configuration commands permit outgoing Telnet
1843 access from line 1 on the NAS *only* to hosts on network 192.85.55.0:
1845 access-list 12 permit 192.85.55.0 0.0.0.255
1849 Note: you must define "access-list 12 permit 192.85.55.0 0.0.0.255" on
1850 the NAS. Only then can you use the acl avpair to apply it to a line
1851 that a user dials in on.
1853 Alternatively, you can try configuring "transport preferred none" on
1854 the lines in question. This will force a user to always type "telnet
1855 10.0.1.6" in order to telnet out from the NAS. Then you can apply
1856 command authorization to this command to restrict it.
1858 Q). I have an autocommand configured in the NAS-local database and I'm
1859 using "aaa authentication local-override". The autocommand doesn't
1860 work, but the username/password does. Why?
1862 A). The "local-override" only applies to the authentication portion of
1863 the local database, so if you want an autocommand for this user, you
1866 aaa authorization exec local if-authenticated
1868 This will use the local DB entry if one exists, allow authenticated
1869 users otherwise, or fail.
1871 We don't have a "aaa authorization local-override" like we do for
1872 authentication. Unlike authentication, the local method for
1873 authorization is sort of equivalent to a local-override.
1875 Q). Can tacacs+ only be enabled on a global basis? I want to
1876 selectively turn it on for, e.g. only modem-connected lines. How do I
1879 A). You turn tacacs+ ON on a global basis, but you can then change the
1880 behavior of individual lines to whatever you want, e.g.
1882 aaa authentication login default tacacs+ none
1883 aaa authentication login oldstyle line
1884 aaa authentication login none none
1886 login authentication default
1888 login authentication oldstyle
1890 login authentication none
1892 Note that unfortunately, you can't (yet) apply authorization
1893 differently to selected lines and interfaces.
1895 Q). I have leased lines running PPP, and AAA authorization is also
1896 configured, so the authorization on the leased lines fails. What should
1899 A). Since you can't (yet) configure authorization on a per-line basis,
1900 you have to turn on authentication on the leased lines running PPP and
1901 configure your T+ server so that it will authorize these lines
1904 A more demanding alternative is to modify the TACACS+ server source code
1905 to allow any authorizations coming in from the port "SerialXXX" to
1908 A third possibility is to not use PPP on those lines, e.g. use HDLC
1909 instead. HDLC doesn't require authentication or authorization.
1911 Q). What are the memory recommendations for TACACS+?
1913 A). Unless you're using passwd style files, TACACS+ holds entries in
1914 hash tables in memory. The overhead is modest e.g. each user entry
1915 occupies 72 bytes, plus space for strings like username and password
1916 etc. Access time should thus be pretty constant regardless of number
1917 of users. On a sparc 2, a config file containing 2000 users requires
1920 Q). How many users will a TACACS+ server support? What happens when
1921 the maximum is exceeded?
1923 There are 2 issues. The first is that each entry in the config file
1924 occupies memory (swap space) so you could run out of swap space either
1925 starting up the daemon or when it forks to answer incoming requests
1926 (see above). If this happens, the daemon will drop the connection
1927 which should appear as an error to the NAS) and the logfile will
1928 contain appropriate error messages. The solution is usually to add
1929 more disk space for swapping.
1931 The second issue is speed: Using config files containing 75,000 user
1932 entries, I'm seeing about 3 authentications per second on a sparc 2
1933 without noticeable performance impact, though I haven't benchmarked
1936 So more than about 3 authentications per second on this platform will
1937 result in users seeing delays and having to wait for prompts. The
1938 usual solution to this is to add more daemons to spread the load out.
1940 Q). How many characters may a TACACS+ Username and Password contain?
1942 A). The short answer is 31 bytes of username, with up to 254 bytes of
1943 password if they are cleartext (8 bytes if passwords are des
1946 The long answer is that the Cisco NAS allocates a buffer of 1024
1947 bytes, so this is the maximum you can type in, in response to a NAS
1950 But the protocol spec allows a username or password length field of
1951 just one byte in an authentication packet, so only the first 255 of
1952 these characters can be sent to the daemon.
1954 Then, the API spec states that the username in the identity structure
1955 on the daemon is 32 bytes long, so only the first 31 bytes of username
1956 will be copied from the authentication packet into this structure,
1957 which is then null-terminated.
1959 The password, on the other hand, is copied into malloc'ed memory, so
1960 it can still be up to 255 characters long.
1962 Now if it's a des encrypted password, then only the first 8 bytes are
1963 significant, per the common unix implementations of crypt.
1965 Lastly, there is also the question of how long a username/password can
1966 be configured in the daemon configuration file. The answer is given by
1967 the value of MAX_INPUT_LINE_LEN, currently set to 255, which
1968 determines the length of the longest string you can enter in the
1971 Q). What is the format of accounting records?
1973 Accounting records are text lines containing tab-separated fields. The
1974 first 6 fields are always the same. These are:
1976 timestamp, NAS name, username, port, address, record type.
1978 Following these, a variable number of fields are written, depending on
1979 the accounting record type. All are of the form attribute=value. There
1980 will always be a task_id field.
1982 Current attributes are:
2000 "callback-dialstring"
2005 I expect more will be added over time.
2007 Example records are thus:
2009 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
2010 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
2011 Thu Jul 13 14:09:02 1995 cherub.cisco.com billw tty18 171.69.1.152 start task_id=17150 service=exec port=18
2012 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
2015 Elapsed time is in seconds, and is the field most people are usually
2018 Q). How do I limit the number of sessions a user can have?
2020 A). The TACACS+ daemon can enforce how many simultaneous sessions a
2021 given user is allowed to have. You must compile the daemon with the
2022 MAXSESS symbol defined (see the Makefile).
2024 Maximum sessions are configured on the daemon for a user as follows:
2027 login = cleartext XXX
2029 # only allow two sessions max for joeslip
2032 name = "Joe SLIP User"
2036 It can also be configured under a group:
2038 group = slip_users {
2049 The daemon keeps a count of how many sessions a given user owns by
2050 monitoring START and STOP accounting records. Thus, exec and network
2051 accounting must be configured for this feature to operate for exec and
2054 As the restriction is enforced during the authorization phase of
2055 login, exec and network authorization must be configured as well, viz:
2057 aaa authentication login default tacacs+
2058 aaa authentication ppp default tacacs+
2059 aaa authorization exec tacacs+
2060 aaa authorization network tacacs+
2061 aaa accounting exec start-stop tacacs+
2062 aaa accounting network start-stop tacacs+
2064 Due to network outages (or other disruptions), it is possible for the
2065 TACACS+ daemon's record of usage to become out of sync with reality,
2066 so before denying access because it thinks a user is running too many
2067 sessions, the TACACS+ daemon will use the finger service on the NAS to
2068 verify how many sessions a user is running there.
2070 If the result of finger indicates that the daemon should permit
2071 access, access will be granted. Note that for this check to work via
2072 finger, "service finger" must also be configured on the NAS.
2074 Lastly, note that because finger output truncates usernames at 10
2075 characters, you may encounter trouble if you have users whose names
2076 are not unique within those first 10 characters.
2078 Also recall that authorization works differently on the console. So
2079 many people locked themselves out of their boxes after configuring
2080 authorization, that we stopped requiring authorization on the console
2081 for authenticated users. Since there's no authorization on the
2082 console, MAXSESS is not enforced there.
2084 Q). How can I configure time-outs on an interface via Tacacs+?
2086 A). Certain per-user/per-interface timeouts may be set by Tacacs+
2087 during authorization. As of 11.0, you can set an arap session timeout,
2088 and an exec timeout. As of 11.1 you can also set an exec idle timeout.
2090 There are currently no settable timeouts for PPP or SLIP sessions, but
2091 there is a workaround which applies to ASYNC PPP/SLIP idle timeouts
2092 started via exec sessions only: This workaround is to set an EXEC
2093 (idletime) timeout on an exec session which is later used to start up
2094 PPP or SLIP (either via a T+ autocommand or via the user explicitly
2095 invoking PPP or SLIP). In this case, the exec idle timeout will
2096 correctly terminate an idle PPP or SLIP session. Note that this
2097 workaround cannot be used for sessions which autoselect PPP or SLIP.
2099 An idle timeout terminates a connection when the interface is idle for
2100 a given period of time (this is equivalent to the "session-timeout"
2101 Cisco IOS configuration directive). The other timeouts are
2102 absolute. Of course, any timeouts set by Tacacs+ apply only to the
2107 login = cleartext foobar
2109 # disconnect lol if there is no traffic for 5 minutes
2111 # disconnect lol unconditionally after one hour
2115 You also need to configure exec authorization on the NAS for the above
2118 aaa authorization exec tacacs+
2120 Note that these timeouts only work for async lines, not for ISDN
2124 Note also that you cannot use the authorization "if-authenticated"
2125 option with these parameters, since that skips authorization if the
2126 user has successfully authenticated.
2128 Q). How do I send VPDN forwarding decisions to an authorization
2131 A). In 11.2 onwards, VPDN NASs can use T+ to allow an authorization
2132 server to make the decision to forward users.
2134 If VPDN forwarding is turned on, and the username is of the form
2135 user@domain, and "domain" matches a vpdn outgoing configured domain,
2136 then an authorization attempt is made for "domain" (see below).
2138 When making an authorization call for VPDN, a service type of "ppp"
2139 with a protocol type of "vpdn", with a username of "domain" will be
2140 made e.g. when a PPP user comes up on a line with the username
2141 foo@bar.com, if "vpdn enable" and "aaa authorization ...." is enabled
2142 on the box, then a one-time authorization of the name "bar.com" is
2145 If this authorization is successful, no local authentication is
2146 attempted on the NAS, and the connection is forwarded via VPDN
2149 If no VPDN-specific information comes back from this authorization
2150 call, the login proceeds as follows:
2152 If tacacs-server directed-requests are configured (note: this is true
2153 by default), then IOS will strip off the domain part of a name of the
2154 form user@domain and use "domain" to try and select a T+ server. If
2155 successful, the username portion "user", without the domain, will be
2156 used for all subsequent authentication, authorization and accounting.
2158 If directed requests are turned off, then the entire username
2159 user@domain is treated as a username.
2161 vpdn specific information includes the attributes "tunnel-id",
2162 "source-ip" (deprecated) and "ip-addresses":
2165 This AV pair specifies the username that will be used to
2166 authenticate the tunnel over which the individual user MID
2167 will be projected. This is analogous to the "NAS name" in the
2168 "vpdn outgoing" command.
2171 This is a list of possible IP addresses that can be used for
2172 the end-point of the tunnel. Consult the text at the end of
2173 this document for more details on how to configure this
2176 source-ip: (This is now deprecated. It began in release 11.2(1.4),
2177 and was removed in 11.2(4.0.2)).
2178 This ip address will be used as the source of all VPDN packets
2179 generated as part of the VPDN tunnel (see the source-ip
2180 keyword in the vpdn outgoing command).
2185 The following syntax is used on the public domain Tacacs+ server.
2188 service = ppp protocol = vpdn {
2189 tunnel-id = <name for tunnel authentication>
2190 ip-addresses = <addr> [<addr> ...]
2191 source-ip = <ip-address>
2195 In addition the T+ server can be used to store the usernames for both
2196 the NAS (the username specified by "tunnel-id" above) and the Home
2197 Gateway. These will be used to authenticate the tunnel.
2201 user = foobar.cisco.com {
2202 service = ppp protocol = vpdn {
2204 ip-addresses = "173.20.12.19 173.20.12.20"
2205 source-ip = 173.5.10.1
2210 global = cleartext egad
2213 user = my_home_gateway {
2214 global = cleartext wowser
2220 To enable AAA assisted VPDN forwarding on a NAS, the following minimum
2221 configuration is required:
2225 aaa authorization network tacacs+ ...
2227 In addition, if the passwords for the home gateway and NAS are stored
2228 on the T+ daemon, the command
2230 aaa authentication login tacacs+ ....
2232 should also be present.
2234 Beginning with release 11.2(1.4), the additional configuration
2236 vpdn outgoing cisco.com ip NAS [ source-ip X.X.X.X ]
2238 can be used. This changes in 11.2(4.0.2) and becomes:
2240 vpdn source-ip X.X.X.X
2241 vpdn outgoing cisco.com ip NAS
2244 Q). Can someone expand on the use of the "optional" keyword.
2246 A). Most attributes are mandatory i.e. if the daemon sends them to the
2247 NAS, the NAS must obey them or deny the authorization. This is the
2248 default. It is possible to mark attributes as optional, in which case
2249 a NAS which cannot support the attribute is free to simply ignore it
2250 without causing the authorization to fail.
2252 This was intended to be useful in cutover situations where you have
2253 multiple NASes running different versions of IOS, some of which
2254 support more attributes than others. If you make the new attributes
2255 optional, older NASes could ignore the optional attributes while new
2256 NASes could apply them. Note that this weakens your security a little,
2257 since you are no longer guaranteed that attributes are always applied
2258 on successful authorization, so it should be used judiciously.
2260 Q). Can I do do address pooling on the T+ daemon?
2262 A). Not really since nothing on the daemon tracks whether an address
2263 is already in use. The best way to do manage address pools is to
2264 define a non-overlapping pool of addresses on each NAS and return the
2265 name of this pool during authorization whenever a user logs in e.g.
2269 ip local pool foo 1.0.0.1 1.0.0.10
2274 service = ppp protocol = ip {
2280 Q). What about MSCHAP?
2282 A). Version F4.X contains mschap support. Mschap is configured the
2283 same way as chap, only using the "mschap" keyword in place of the
2286 Like ARAP, MSCHAP works best when you have a des library (see the note
2287 at the beginning of this document), but this is optional, as the DES
2288 calculation can be done by the NAS instead. It also optionally
2289 requires a key from Microsoft which is not public domain, but this can
2290 also be done on the NAS too, so you can live without it.
2292 To compile the daemon with MSCHAP support, uncomment the MSCHAP line
2293 in the Makefile. This will add the MSCHAP code to your daemon. You can
2294 leave MSCHAP_DES undefined, in which case the MSCHAP DES calculation
2295 will be done by NAS, and no special MSCHAP key will be required.
2297 If you have a DES library and want to use it with MSCHAP (this is more
2298 efficient for authentication), then you can also uncomment the
2299 MSCHAP_DES and MSCHAP_MD4_SRC lines in the Makefile. This will ensure
2300 that the DES calculation done in the daemon. A key will need to be
2301 obtained from Microsoft and used to replace the definition of
2302 MSCHAP_KEY in the file mschap.h. If you're thinking by now that this
2303 is all too much trouble, I can't say I blame you....
2305 Q). Can I do wtmp-style logging like xtacacd used to do?
2307 A). Wtmp file logging is supported. The "-u <wtmpfilename>" command
2308 line flag can be used to specify a filename which will be used for
2309 logging wtmp style records instead of the regular T+ accounting
2312 wtmp records are generated into wtmpfilename. Since file locking is
2313 also used when writing to wtmpfilename, the usual provisos regarding
2314 NFS and locking (see accounting above) should be observed.
2316 To generate correct wtmp log records, the NAS needs to be configured
2319 aaa accounting exec stop-only tacacs+
2320 aaa accounting network stop-only tacacs+
2321 aaa accounting system start-stop tacacs+
2323 CANNED CONFIGURATIONS
2324 ---------------------
2326 Here are some canned configurations for getting demos started:
2328 1). A canned configuration for login authentication only. This allows
2329 user fred to login with password "abcdef". If the tacacs+ server dies,
2330 the enable secret will be accepted as a login password instead.
2336 # repeat as necessary for each user
2338 login = cleartext abcdef
2344 enable secret foobar
2345 ! use tacacs+. If server dies, use the enable secret password
2346 aaa authentication login default tacacs+ enable
2347 tacacs-server host <some host ip address>
2348 tacacs-server key <some key>
2350 2). A canned configuration for command authorization. This will allow
2351 user fred to login with password abcdef and to run the privileged
2352 (level 15) commands 'write terminal' and 'configure'. All other
2353 privileged commands will be denied.
2355 The "none" keyword in the NAS configuration line means that if the
2356 tacacs+ server dies, any command will be allowed.
2362 # repeat as necessary for each user
2364 login = cleartext abcdef
2377 ! all level 15 (privileged commands). If server dies, allow everything
2378 aaa authorization commands 15 tacacs+ none
2379 tacacs-server host <some host ip address>
2380 tacacs-server key <some key>
2382 3). Canned configuration for network access authorization. This config
2383 allows "fred" to login to line 1 with password abcdef (or to and to
2384 run ppp using chap authentication. The chap password is "lab".
2390 # repeat as necessary for each user
2392 login = cleartext abcdef
2393 chap = cleartext lab
2394 service = ppp protocol = ip {
2402 ! authenticate exec logins (if not autoselecting)
2403 aaa authentication login default tacacs+
2404 ! authorize network services via tacacs+
2405 aaa authorization network tacacs+
2406 ! use tacacs+ for authenticating ppp users
2407 aaa authentication ppp default tacacs+
2408 tacacs-server host <some host ip address>
2409 tacacs-server key <some key>
2411 ip address 1.0.0.1 255.0.0.0
2412 async default ip address 172.21.14.55
2414 async dynamic address
2415 async mode interactive
2416 ! use chap to authenticate ppp users
2417 ppp authentication chap
2419 ! need "modem inout" here and flow control if using a modem
2421 4). Canned configuration for ARAP.
2426 aaa authentication arap default guest tacacs+
2427 aaa authorization network tacacs+
2428 aaa accounting network start-stop tacacs+
2431 arap network <number> <name>
2434 appletalk cable-range <range>
2435 appletalk zone <zonename>
2437 tacacs-server host <host>
2438 tacacs-server key <key>
2442 modem answer-timeout 0
2445 autoselect during-login
2448 flowcontrol hardware
2455 arap = cleartext <arap secret>
2459 Authorization AV pairs
2460 ----------------------
2461 The following authorization AV pairs are supported by 10.3(3) onwards
2462 except where specifically noted.
2464 The following AV pairs specify which service is being authorized. They
2465 are typically accompanied by protocol AV pairs and other, additional
2466 pairs from the lists below.
2469 service=shell (for exec startup, and also for command authorizations)
2473 service=system (not used).
2476 Used for managing reverse telnet connections e.g.
2479 login = cleartext lab
2481 port#1 = nasname1/tty2
2482 port#2 = nasname2/tty5
2486 Requires IOS configuration
2488 aaa authorization reverse-access tacacs+
2490 See the IOS docs for more details.
2493 The lower layer of PPP, always brought up before IP, IPX, etc.
2497 Used with service=ppp and service=slip to indicate which
2498 protocol layer is being authorized.
2502 Used with service=ppp to indicate which protocol layer
2503 is being authorized.
2506 with service=ppp or service=arap
2512 Authorization of CCP. Compression Control Protocol). No other
2513 av-pairs associated with this.
2516 Authorization of CDP (Cisco Discovery Protocol). No other
2517 av-pairs associated with this.
2520 Authorization of multilink PPP. See 'max-links' and 'load-threshold'.
2523 For undefined/unsupported conditions. Should not occur under
2524 normal circumstances.
2527 If the value of cmd is NULL e.g. the AV pair is cmd=, then
2528 this is an authorization request for starting an exec.
2530 If cmd is non-null, this is a command authorization request,
2531 It contains the name of the command being authorized
2535 During command authorization, the name of the command is given
2536 by an accompanying "cmd=" AV pair, and each command argument
2537 is represented by a cmd-arg AV pair e.g. cmd-arg=archie.sura.net
2539 NOTE: 'cmd-arg' should never appear in a configuration file.
2540 It is used internally by the daemon to construct a string
2541 which is then matched against the regular expressions which appear
2542 in a cmd clause in the configuration file.
2545 For ARAP this contains an access-list number. For EXEC
2546 authorization it contains an access-class number, e.g. acl=2.
2547 which is applied to the line as the output access class equivalent
2548 to the configuration command
2553 An outbound access-class is the best way to restrict outgoing telnet
2554 connections. Note that a suitable access list (in this case,
2555 numbered 2) must be predefined on the NAS.
2558 This AV pair contains an IP or IPX input access list number
2559 for slip or PPP e.g. inacl=2. The access list itself must be
2560 pre-configured on the Cisco box. Per-user access lists do not
2561 work with ISDN interfaces unless you also configure a virtual
2562 interface. After 11.2(5.1)F, you can also use the name of a
2563 predefined named access list, instead of a number, for the
2564 value of this attribute.
2566 Note: For IPX, inacl is only valid after 11.2(4)F.
2568 inacl#<n> (PPP/IP, PPP/IPX, 11.2(4)F)
2569 This AV pair contains the definition of an input access list
2570 to be installed and applied to an interface for the duration
2571 of the current connection, e.g.
2573 inacl#1="permit ip any any precedence immediate"
2574 inacl#2="deny igrp 0.0.1.2 255.255.0.0 any"
2576 Attributes are sorted numerically before they are applied.
2577 For IP, standard OR extended access list syntax may be used,
2578 but it is an error to mix the two within a given access-list.
2580 For IPX, only extended access list syntax may be used.
2585 sho ipx access-lists
2590 outacl (PPP/IP, PPP/IPX)
2591 This AV pair contains an IP or IPX output access list number
2592 for SLIP. PPP/IP or PPP/IPX connections e.g. outacl=4. The
2593 access list itself must be pre-configured on the Cisco
2594 box. Per-user access lists do not work with ISDN interfaces
2595 unless you also configure a virtual interface. PPP/IPX is
2596 supported in 11.1 onwards only. After 11.2(5.1)F, you can also
2597 use the name of a predefined named access list, as well as a
2598 number, for the value of this attribute.
2601 outacl#<n> (PPP/IP, PPP/IPX, 11.2(4)F)
2602 This AV pair contains an output access list definition to be
2603 installed and applied to an interface for the duration of the
2604 current connection, e.g.
2606 outacl#1="permit ip any any precedence immediate"
2607 outacl#2="deny igrp 0.0.9.10 255.255.0.0 any"
2609 Attributes are sorted numerically before they are applied.
2610 For IP, standard OR extended access list syntax may be used,
2611 but it is an error to mix the two within a given access-list.
2613 For IPX, only extended access list syntax may be used.
2618 sho ipx access-lists
2624 The IP address the remote host should be assigned when a slip
2625 or PPP/IP connection is made e.g. addr=1.2.3.4
2627 routing (SLIP, PPP/IP)
2628 Equivalent to the /routing flag in slip and ppp commands. Can
2629 have as its value the string "true" or "false".
2631 timeout (11.0 onwards, ARAP, EXEC)
2632 Sets the time until an arap or exec session disconnects
2633 unconditionally (in minutes), e.g. timeout=60
2636 During exec startup, this specifies an autocommand, like the
2637 autocommand option to the username configuration command,
2638 e.g. autocmd="telnet foo.com"
2641 During exec startup, this specifies "noescape", like the
2642 noescape option to the username configuration command. Can
2643 have as its value the string "true" or "false",
2647 During exec startup, this specifies "nohangup", like the
2648 nohangup option to the username configuration command. Can
2649 have as its value the string "true" or "false",
2653 Specifies the current privilege level for command
2654 authorizations, a number from zero to 15 e.g. priv_lvl=5.
2656 Note: in 10.3 this attribute was priv_lvl i.e.
2657 it contained an underscore instead of a hyphen.
2660 An Appletalk zonelist for arap equivalent to the line
2661 configuration command "arap zonelist" e.g. zonelist=5
2663 addr-pool (11.0 onwards, PPP/IP, SLIP)
2664 This AV pair specifies the name of a local pool from which to
2665 get the IP address of the remote host.
2667 Note: addr-pool works in conjunction with local pooling. It
2668 specifies the name of a local pool (which needs to be
2669 pre-configured on the NAS). Use the ip-local pool command to
2670 declare local pools, e.g on the NAS:
2672 ip address-pool local
2673 ip local pool foo 1.0.0.1 1.0.0.10
2674 ip local pool baz 2.0.0.1 2.0.0.20
2676 then you can use Tacacs+ to return addr-pool=foo or
2677 addr-pool=baz to indicate which address pool you want to get
2678 this remote node's address from, e.g. on the daemon:
2681 service = ppp protocol = ip {
2686 route (11.1 onwards, PPP/IP, SLIP).
2687 This AV pair specifies a route to be applied to an interface.
2689 During network authorization, the "route" attribute may be
2690 used to specify a per-user static route, to be installed via
2693 The daemon side declaration is:
2695 service=ppp protocol=ip {
2696 route="<dst_addr> <mask> [ <gateway> ]"
2699 This indicates a temporary static route that is to be
2700 applied. "<dst_address>, <mask> and [<gateway>]" are expected
2701 to be in the usual dotted-decimal notation, with meanings the
2702 same as for the familiar "ip route" configuration command on a
2705 If gateway is omitted, the peer's address is taken to be the gateway.
2707 The route is expunged once the connection terminates.
2709 route#<n> (PPP/IP/IPX, 11.2(4)F)
2710 Same as the "route" attribute, except that these are valid for
2711 IPX as well as IP, and they are numbered, allowing multiple
2712 routes to be applied e.g.
2714 route#1="3.0.0.0 255.0.0.0 1.2.3.4"
2715 route#2="4.0.0.0 255.0.0.0"
2720 route#1="4C000000 ff000000 30.12.3.4"
2721 route#2="5C000000 ff000000 30.12.3.5"
2729 callback-rotary (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2730 The number of a rotary group (between 0 and 100 inclusive)
2731 to use for callback e.g. callback-rotary=34. Not valid for ISDN.
2733 callback-dialstring (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2734 sets the telephone number for a callback e.g.
2735 callback-dialstring=408-555-1212. Not valid for ISDN.
2737 callback-line (11.1 onwards, valid for ARAP, EXEC, SLIP or PPP)
2738 The number of a tty line to use for callback e.g.
2739 callback-line=4. Not valid for ISDN.
2741 nocallback-verify (11.1 onwards, valid for ARAP, EXEC)
2742 Indicates that no callback verification is required. The only
2743 valid value for this parameter is the digit one i.e.
2744 nocallback-verify=1. Not valid for ISDN.
2746 idletime (11.1 onwards, EXEC)
2747 Sets a value, in minutes, after which an IDLE session will be
2748 terminated. N.B. Does NOT work for PPP.
2750 tunnel-id (11.2 onwards, PPP/VPDN)
2751 This AV pair specifies the username that will be used to
2752 authenticate the tunnel over which the individual user MID
2753 will be projected. This is analogous to the "NAS name" in the
2754 "vpdn outgoing" command.
2756 ip-addresses (11.2 onwards, PPP/VPDN)
2757 This is a space separated list of possible IP addresses that
2758 can be used for the end-point of the tunnel.
2760 In 11.2(5.4)F, this attribute was extended as follows:
2762 1) comma (',') is also consider as a delimiter
2763 For example the avpair can now be written as
2765 ip-addresses = 172.21.9.26,172.21.9.15,172.21.9.4
2767 2) '/' is considered a priority delimiter. When you have a
2768 number of Home Gateway routers, it is desirable to consider some
2769 as the primary routers and some as backup routers.
2771 The '/' allow you to config the routers into priority groups,
2772 so that the NAS will try to forward the users to the high
2773 priority routers, before forwarding to the low priority one.
2775 For example in the following avpair:
2777 ip-addresses = "172.21.9.26 / 172.21.9.15 / 172.21.9.4"
2779 172.21.9.26 is considered to be priority 1
2780 172.21.9.15 is considered to be priority 2
2781 172.21.9.4 is considered to be priority 3
2783 The NAS will try to forward the users to 172.21.9.26, before
2784 trying 172.21.9.15. If the NAS can't forward users to
2785 172.21.9.26, it will try 172.21.9.15 next. If it fails with
2786 172.21.9.15, it will then try forwarding to 172.21.9.4.
2788 source-ip (PPP/VPDN, now deprecated, only existed in releases 11.2(1.4)
2789 thru 11.2(4.0.2)). This specifies a single ip address will be
2790 used as the source of all VPDN packets generated as part of
2791 the VPDN tunnel (see the equivalent source-ip keyword in the
2792 IOS vpdn outgoing command).
2794 nas-password (PPP/VPDN, 11.2(3.4)F, 11.2(4.0.2)F)
2795 During L2F tunnel authentication, nas-password specifies the password
2798 gw-password (PPP/VPDN, 11.2(3.4)F, 11.2(4.0.2)F)
2799 During L2F tunnel authentication, gw-password specifies the password
2800 for the home gateway.
2802 rte-ftr-in#<n> (PPP -- IP/IPX, 11.2(4)F)
2803 This AV pair specifies an input access list definition to be
2804 installed and applied to routing updates on the current
2805 interface, for the duration of the current connection.
2807 For IP, both standard and extended Cisco access list syntax is
2808 recognised, but it is an error to mix the two within a given
2811 For IPX, only Cisco extended access list syntax is legal.
2813 Attributes are sorted numerically before being applied. For
2814 IP, the first attribute must contain the name of a routing
2815 process and its identifier (except for rip, where no
2816 identifier is needed), e.g.
2818 rte-fltr-in#0="router igrp 60"
2819 rte-fltr-in#1="permit 0.0.3.4 255.255.0.0"
2820 rte-fltr-in#2="deny any"
2822 For IPX, no routing process is needed, e.g.
2824 rte-fltr-in#1="deny 3C01.0000.0000.0001"
2825 rte-fltr-in#2="deny 4C01.0000.0000.0002"
2829 show ip access-lists
2831 sho ipx access-lists
2836 Related IOS commands:
2838 router <routing process identifier>
2839 [no] distribute-list <list-name> in <interface>
2842 ipx input-network-filter <access-list-number>
2845 rte-ftr-out#<n> (PPP/IP, 11.2(4)F)
2846 This AV pair specifies an input access list definition to be
2847 installed and applied to routing updates on the current
2848 interface, for the duration of the current connection.
2850 For IP, both standard and extended Cisco access list syntax is
2851 recognised, but it is an error to mix the two within a given
2854 Attributes are sorted numerically before being applied. The
2855 first attribute must contain the name of a routing process and
2856 its identifier (except for rip, where no identifier is
2859 rte-fltr-out#0="router igrp 60"
2860 rte-fltr-out#3="permit 0.0.5.6 255.255.0.0"
2861 rte-fltr-out#4="permit any"
2863 For IPX, no routing process is specified, e.g.
2865 rte-fltr-out#1="deny 3C01.0000.0000.0001"
2866 rte-fltr-out#2="deny 4C01.0000.0000.0002"
2870 sho ipx access-lists
2872 show ip access-lists
2877 Related IOS commands:
2879 router <routing process identifier>
2880 [no] distribute-list <list-name> in <interface>
2883 ipx output-network-filter <access-list-number>
2886 sap#<n> (11.2(4)F PPP/IPX)
2887 This AV pair specifies static saps to be installed for the duration
2888 of a connection e.g.
2890 sap#1="4 CE1-LAB 1234.0000.0000.0001 451 4"
2891 sap#2="5 CE3-LAB 2345.0000.0000.0001 452 5"
2893 The syntax of static saps is the same as that used by the IOS
2901 Related IOS commands:
2905 route#<n> (PPP/IP/IPX, 11.2(4)F)
2907 Same as the "route" attribute, except that these are valid for
2908 IPX as well as IP, and they are numbered, allowing multiple
2909 routes to be applied e.g.
2911 route#1="3.0.0.0 255.0.0.0 1.2.3.4"
2912 route#2="4.0.0.0 255.0.0.0"
2917 route#1="4C000000 ff000000 30.12.3.4"
2918 route#2="5C000000 ff000000 30.12.3.5"
2927 sap-fltr-in#<n> (PPP/IPX, 11.2(4)F)
2928 This AV pair specifies an input sap filter access list
2929 definition to be installed and applied on the current
2930 interface, for the duration of the current connection.
2932 Only Cisco extended access list syntax is legal, e.g
2934 sap-fltr-in#1="deny 6C01.0000.0000.0001"
2935 sap-fltr-in#2="permit -1"
2937 Attributes are sorted numerically before being applied.
2939 sho ipx access-lists
2944 [no] ipx input-sap-filter <number>
2947 sap-fltr-out#<n> (PPP/IPX 11.2(4)F)
2948 This AV pair specifies an output sap filter access list
2949 definition to be installed and applied on the current
2950 interface, for the duration of the current connection.
2952 Only Cisco extended access list syntax is legal, e.g
2954 sap-fltr-out#1="deny 6C01.0000.0000.0001"
2955 sap-fltr-out#2="permit -1"
2957 Attributes are sorted numerically before being applied.
2959 sho ipx access-lists
2964 [no] ipx output-sap-filter <number>
2968 pool-def#<n> (PPP/IP, 11.2(4)F)
2969 This attribute is used to define ip address pools on the NAS.
2971 During IPCP address negotiation, if an ip pool name is
2972 specified for a user (see the addr-pool attribute), a check is
2973 made to see if the named pool is defined on the NAS. If it is,
2974 the pool is consulted for an ip address.
2976 If the required pool is not present on the NAS (either in the
2977 local config, or as a result of a previous download
2978 operation), then an authorization call to obtain it is
2979 attempted, using the special username:
2983 where <nas-name> is the configured name of the NAS.
2985 Note: This username can be changed using the IOS configuration
2988 aaa configuration config-name nas1-pools-definition.cisco.us
2990 The pool-def attribute is used to define ip address pools for
2991 the above authorization call e.g.
2994 login = cleartext lab
2995 service = ppp protocol = ip {
3001 service = ppp protocol = ip {
3002 pool-def#1 = "aaa 1.0.0.1 1.0.0.3"
3003 pool-def#2 = "bbb 2.0.0.1 2.0.0.10"
3004 pool-def#3 = "ccc 3.0.0.1 3.0.0.20"
3010 In the example above is a configuration file fragment for defining 3
3011 pools named "aaa", "bbb" and "ccc" on the NAS named "nas1".
3013 When the user "foo" refers to the pool named "bbb", if the
3014 pool "bbb" isn't defined, the NAS will attempt to download the
3015 definition contained in the "nas1-pools" entry.
3017 The other pools will also be defined at the same time (or they
3018 will be ignored if they are already defined).
3020 Since this procedure is only activated when an undefined pool
3021 is referenced, one way to redefine a pool once it has been
3022 downloaded is to manually delete the definition e.g. by
3023 logging into the NAS, enabling, and configuring:
3026 no ip local pool bbb
3029 When a pool is deleted, there is no interruption in service
3030 for any user who is currently using a pool address. If a pool
3031 is deleted and then subsequently redefined to include a pool
3032 address that was previously allocated, the new pool will pick
3033 up the allocated address and track it as expected.
3035 Since downloaded pools do not appear in the NAS configuration,
3036 any downloaded pool definitions automatically disappear
3037 whenever a NAS reboots. These pools are marked as "dynamic"
3038 when they appear in the output of the "show ip local pools"
3041 Since it is desirable not to have to manually delete pools to
3042 redefine them, the AV pair pool-timeout=<n> can be used to
3043 timeout any downloaded pool definitions. The timeout <n> is in
3046 The effect of the pool-timeout attribute is to start a timer
3047 when the pool definitions are downloaded. When the timer
3048 expires, the pools are deleted. The next reference to a
3049 deleted pool via will cause a re-fetch of the pool
3050 definitions. This allows pool changes to be made on the
3051 daemon and propagated to the NAS in a timely manner.
3056 sho ip local pool <pool-name>
3060 ip local pool <name> <start address> <end address>
3063 old-prompts (PPP/SLIP)
3064 This attribute is integrated into the following IOS images:
3066 11.2(7.4)P 11.2(7.4) 11.1(13.1) 11.(16.2) 11.1(13.1)AA
3067 11.1(13.1)CA 11.1(13.1)IA 11.2(8.0.1)F 11.0(16.2)BT)
3069 This attribute allows providers to make the prompts in T+
3070 appear identical to those of earlier systems (tacacs and
3071 xtacacs). This will allow administrators to upgrade from
3072 tacacs/xtacacs to T+ transparently to users.
3074 The difference between the prompts is as follows:
3076 In xtacacs, when the user types "slip" or "ppp" the system
3077 prompts for an address followed by a password, whereas T+
3078 prompts only for an address.
3080 In xtacacs, if the user types "slip host" or "ppp host", the
3081 system prompts for a password. In T+, there is no prompt.
3083 Using this attribute, T+ can be made to mimic the prompting
3084 behaviour of xtacacs, by configuring network authorization on
3085 IOS, and using the "old-prompts=true" attribute value pair for
3086 slip and ppp/ip, viz:
3089 global = cleartext foo
3094 default attribute = permit
3097 service = ppp protocol = ip {
3098 default attribute = permit
3103 i.e. the prompts are controlled by the addition of the
3104 "old-prompts=true" attribute.
3107 max-links (PPP/multilink - Multilink parameter; 11.3)
3108 This AV pair restricts the number of multilink bundle links
3109 that a user can have.
3111 The daemon side declaration is:
3113 service=ppp protocol=multilink {
3117 The range of <n> is [1-255].
3119 Related NAS commands:
3122 int virtual-template X
3123 multilink max-links <n>
3128 load-threshold (PPP/multilink - Multilink parameter; 11.3)
3129 This AV pair sets the load threshold at which an additional
3130 multilink link is added to the bundle (if load goes above) or
3131 deleted (if load goes below).
3133 The daemon side declaration is:
3135 service=ppp protocol=multilink {
3139 The range of <n> is [1-255].
3141 Related NAS commands:
3144 int virtual-template X
3145 multilink load-threshold <n>
3151 Reserved for future use:
3153 ppp-vj-slot-compression
3156 x25-addresses (PPP/VPDN)
3157 frame-relay (PPP/VPDN)