lpadmin(ADM) 06 January 1993 lpadmin(ADM) Name lpadmin - configure the print service Syntax /usr/lib/lpadmin -p printer options /usr/lib/lpadmin -x dest /usr/lib/lpadmin -d [ dest ] /usr/lib/lpadmin -S print-wheel -A alert-type [ -W integer ] [ -Q integer ] Description lpadmin configures the lp print service to describe printers and devices. It is used to add and change printers, to remove printers from the ser- vice, to set or change the system default destination, to define alerts for print wheels and to define printers for remote printing services. Adding or changing a printer The first form of the lpadmin command (lpadmin -p printer options) is used to configure a new printer or to change the configuration of an existing printer. The following options are used and may appear in any order. For ease of discussion, the printer will be referred to as ``P'' below. -F fault-recovery Restores the lp print service after a printer fault according to the value of fault-recovery: continue Continues printing on the top of the page where printing stopped. This requires a filter (see lpfilter(ADM)) to wait for the fault to clear before automatically con- tinuing. beginning Starts printing the request again from the beginning. wait Disables printing on the printer and waits for the administrator or a user to enable printing again. During the wait, the administrator or the user who sub- mitted the stopped print request can issue a change request that specifies where printing should resume. If no change request is made before printing is enabled, printing will resume at the top of the page where stopped if the filter allows; otherwise, the request will be printed from the beginning. This option specifies the recovery to be used for any print request that is stopped because of a printer fault. -c class Inserts printer ``P'' into the specified class. class will be cre- ated if it does not already exist. -D comment Saves comment for display whenever a user asks for a full descrip- tion of the printer ``P'' (see lpstat(C)). The lp print service does not interpret this comment. -e printer Copies an existing printer's interface program to be the new inter- face program for printer ``P''. -f allow:form-list -f deny:form-list Allows (-f allow) or denies (-f deny) the forms in form-list to be printed on printer ``P''. For each printer, the lp print service keeps two lists of forms: an ``allow-list'' of forms that can be used with the printer and a ``deny-list'' of forms that shouldn't be used with the printer. With the -f allow option, the forms listed are added to the allow- list and removed from the deny-list. With the -f deny option, the forms listed are removed from the allow-list and added to the deny- list. If the allow-list is not empty, the forms in the list can be used with the printer and all others cannot, regardless of the content of the deny-list. If the allow-list is empty but the deny-list is not, the forms in the deny-list cannot be used with the printer. All forms can be excluded from a printer by having an empty allow-list and putting the word any in the deny-list. All forms can be used on a printer by having an empty deny-list and specifying any for the allow-list, provided the printer can handle all the characteristics of the forms. The lp print service uses this information as a set of guidelines for determining where a form can be mounted. Administrators, how- ever, are not restricted from mounting a form on any printer. If mounting a form on a particular printer is in disagreement with the information in the allow-list or deny-list, the administrator is warned, but the mount is accepted. Nonetheless, if a user attempts to issue a print or change request for a form-and-printer combina- tion that is in disagreement with the information, the request is accepted only if the form is currently mounted on the printer. If the form is later unmounted before the request can print, the request is canceled, and the user is notified by mail. If an administrator tries to name a form as acceptable for use on a printer that doesn't have the capabilities needed by the form, the command is rejected. Note the other use of -f below. -h Indicates that the device associated with printer ``P'' is hardwired. This option is assumed when adding a new printer unless the -l option is supplied. -i interface Establishes a new interface program for printer ``P''. interface is the pathname of the new program. -I content-type-list Assigns printer ``P'' to handle print requests with content of a type listed in content-type-list. The type simple is recognized as the default content-type of files on the system. Such a data stream contains only printable ASCII characters and the following control characters: ____________________________________________________________________ Control character Octal value Meaning ____________________________________________________________________ backspace 010 move back to previous column, except at beginning of line tab 011 move to next tab stop linefeed (newline) 012 move to beginning of next line form feed 014 move to beginning of next page carriage return 015 move to beginning of current line To force the print service to not consider simple as a valid type for the printer, give an explicit value (for example, the printer type) in the content-type-list. If you do want simple included along with other types, you must include simple in the content- type-list. Each printer automatically has its printer type included in the list of content types it will accept. Except for simple, each content-type name is freely determined by the administrator. If names given as content types are also printer types, the names are accepted without comment because the lp print service recognizes all printer types as potential content types as well. -l Indicates that the device associated with ``P'' is a login terminal. The lp scheduler, lpsched(ADM), disables all login terminals auto- matically each time it is started. Before re-enabling ``P'', its current device should be established using lpadmin. -M -f form-name [ -a [ -o filebreak ]] Mounts the form form-name on ``P''. Print requests to be printed with the pre-printed form form-name will be printed on ``P''. If more than one printer has the form mounted and the user has speci- fied any (with the -d option of the lp command) as the printer des- tination, then each print request will be printed on the printer that meets the other needs of the request. The page length and width and character and line pitches needed by the form are compared with those allowed for the printer by checking the capabilities in the terminfo(F) database for the type of print- er. If the form requires attributes that are not available with the printer, the administrator is warned, but the mount is accepted. If the form lists a particular print wheel as mandatory but the print wheel mounted on the printer is different, the administrator is also warned but the mount is accepted. If the -a option is given, an alignment pattern is printed, preceded by the same initialization of the physical printer that precedes a normal print request with one exception: no banner page is printed. Printing is assumed to start at the top of the first page of the form. After the pattern is printed, the administrator can adjust the mounted form in the printer, press <Return> for another align- ment pattern (no initialization this time), and continue printing as many alignment patterns as desired. The administrator can quit printing alignment patterns by typing ``q''. If the -o filebreak option is given, a formfeed is inserted between each copy of the alignment pattern. By default, the alignment pat- tern is assumed to correctly fill a form, so no formfeed is added. A form is unmounted by mounting a new form in its place using the -f option. The -f none option can be used to specify no form. By default, a new printer has no form mounted. Note the other use of -f above. -M -S print-wheel Mounts the print wheel print-wheel on printer ``P''. Print requests to be printed with print-wheel will be printed on that printer. If more than one printer has the print-wheel mounted and the user has specified any (with the -d option of the lp command) as the printer destination, then each print request will be printed on the printer that meets the other needs of the request. If the print-wheel is not listed as acceptable for the printer, the administrator is warned, but the mount is accepted. If the printer does not take print wheels, the command is rejected. A print wheel is unmounted by mounting a new print wheel in its place or by using the -S none option. By default, a new printer has no special print wheel mounted. Until this is changed, a print request that asks for a specific print wheel will not be printed on a new printer with no special print wheel mounted. Note the other uses of the -S option described below. -m model Selects a model interface program provided with the lp print service for a given printer. -o printing-option Each -o option in the list below is the default given to an inter- face program if the option is not taken from a preprinted form description or is not explicitly given by the user submitting a request (see lp(C)). The only -o options that can have defaults defined are listed below: length = scaled-decimal-number width = scaled-decimal-number cpi = scaled-decimal-number lpi = scaled-decimal-number stty = stty-option-list The term scaled-decimal-number refers to a non-negative number used to indicate a unit of size. (The type of unit is shown by a trail- ing letter attached to the number.) Three types of scaled decimal numbers are discussed for the lp print service: numbers that show sizes in centimeters (marked with a trailing ``c''), numbers that show sizes in inches (marked with a trailing ``i''), and numbers that show sizes in units appropriate to use (without a trailing letter), that is, lines, columns, characters per inch (cpi) or lines per inch (lpi). The first four default option values should agree with the capabili- ties of the type of physical printer as defined in the terminfo(F) database for the printer type. If they do not, the command is rejected. The stty-option-list is not checked for allowed values but is passed directly to the stty(C) program by the standard interface program. Any error messages produced by stty when a request is processed (by the standard interface program) are mailed to the user submitting the request. For each printing option not specified, the defaults for the follow- ing attributes are defined in the terminfo entry for the specified printer type: length width cpi lpi The default for stty is stty = 9600 cs8 -cstopb -parenb -paroff ixon -ixany opost -olcuc -onlcr -ocrnl -onocr -onlret -ofill nl0 cr0 tab0 bs0 vt0 ff0 You can set any of the -o options to the default values (which vary for different types of printers) by typing them without assigned values as follows: length= width= cpi= lpi= stty= -o nobanner Allows users to submit a print request that asks that no banner page be printed. -o banner Forces a banner page to be printed with every print request, even when a user asks for no banner page. This is the default; you must specify -o nobanner if you want to allow users to specify -o nobanner with the lp command. -R machine-list Sets up remote machines in machine-list to share print services. The lp print service arranges for the advertising and mounting of all necessary resources and for automatic recovery of shared print services when the machine is brought to a state where RFS is run. The lp spooler keeps the parts of the print service owned by each machine separate, so that the administrator on one machine can change only the service provided by his or her machine. The lp spooler provides for no centrally managed print service using RFS. -r class Removes a given printer from the specified class. If the printer is the last member of the class, then the class will be removed. -S list Allows the aliases for character sets or print wheels named in list to be used with a given printer. If the printer is a type that takes print wheels, then list is a list of print wheel names separated by commas or spaces. These will be the only print wheels considered mountable on the printer. (You can always force a different print wheel to be mounted, however.) Until the option is used to specify a list, no print wheels will be considered mountable on the printer, and print requests that ask for a particular print wheel with this printer will be rejected. If the printer is a type that has selectable character sets, then list is a list of character set name ``mappings'' or aliases separated by commas or spaces. Each ``mapping'' is of the form: known-name = synonym known-name is a character set number preceded by ``cs'', such as ``cs3'' for character set three, or a character set name from the terminfo database ``csnm'' entry. If this option is not used to specify a list, only the names already known from the terminfo data- base or numbers with a prefix of ``cs'' will be acceptable for the printer. If list is the word none, the previous print wheel list or character set aliases will be removed. Note the other uses of the -S option. -T printer-type Assigns the given printer-type, a representation of a physical printer of type printer-type. printer-type is used to extract data from terminfo(F); this data is used to initialize the printer before printing each user's request. Some filters may also use printer- type to convert content for the printer. If this option is not used, the default printer-type will be unknown; no useful informa- tion will be extracted from terminfo(F), so each user request will be printed without first initializing the printer. Also, this option must be used if the following are to work: -o cpi=, -o lpi=, -o width=, and -o length= options of the lpadmin and lp commands, and the -S and -f options of the lpadmin command. -u allow:user-list -u deny:user-list Allows (-u allow) or denies (-u deny) the users in user-list access to a given printer. For normal access to each printer, the lp print service keeps two lists of users: an allow-list of people allowed to use the printer and a deny-list of people denied access to the printer. With the -u allow option, the users listed are added to the allow-list and removed from the deny-list. With the -u deny option, the users listed are removed from the allow-list and added to the deny-list. If the allow-list is not empty, the users in the list are allowed access to the printer and all others are denied access, regardless of the content of the deny-list. If the allow-list is empty but the deny-list is not, the users in the deny-list are denied access and all others are allowed. If both lists are empty, all users are allowed access. Access can be denied to all users except the lp print service administrator by putting any in the deny-list. To allow everyone access to a given printer and effectively empty both lists, put any in the allow-list. -U dial-info Assigns the dialing information dial-info to the printer. dial-info is used with the dial(S) routine to call the printer. Any network connection supported by the Basic Networking Utilities will work. dial-info can be either a phone number for a modem connection or a system name for other kinds of connections. Or if -U direct is given, no dialing will take place because the name direct is reserved for a printer that is directly connected. If a system name is given, it is used to search for connection details from the file /usr/lib/uucp/Systems or related files. The Basic Networking Utili- ties are required to support this option. By default, -U direct is assumed. -v device Associates a new device with a given printer. device is the path- name of a file that is writable by lp. Note that the same device can be associated with more than one printer. -A alert-type [ -W integer ] The -A option is used to send the alert alert-type to the adminis- trator when a printer fault is first detected and periodically thereafter until the printer fault is cleared by the administrator. The alert-types are: mail Sends the alert message via mail (see mail(C)) to the administrator who issues this command. write Writes the message to the terminal on which the administra- tor is logged in. If the administrator is logged in on several terminals, one is chosen arbitrarily. quiet Does not send messages for the current condition. An administrator can use this option to temporarily stop receiving further messages about a known problem. Once the fault has been cleared and printing resumes, messages will again be sent when another fault occurs with the printer. none Does not send messages until this command is given again with a different alert-type; removes any existing alert definition. No alert will be sent when the printer faults until a different alert-type is used (except quiet). shell-command shell-command is run each time the alert needs to be sent. shell-command should expect the message as standard input. If there are blanks embedded in the command, enclose the command in quotes. Note that the mail(C) and write(C) values for this option are equivalent to the values mail user-name and write user-name, respectively, where user-name is the current name for the administrator. This will be the login name of the person submitting this command unless he or she has used the su command to change to another user ID. If the su command has been used to change the user ID, then the user-name for the new ID is used. list The type of the alert for the printer fault is displayed on the standard output. No change is made to the alert. The message sent appears as follows: The print wheel print-wheel needs to be mounted on the printer(s): printer-list number-of-requests print requests await this print-wheel. The printer printer-name has stopped printing for the reason given below. Fix the problem and bring the printer back on line. Print- ing has stopped but will be restarted in a few minutes; issue an enable command if you want to restart sooner. Unless someone issues a change request lp -i request-id -P ... to change the page-list to print, the current request will be repeated from the beginning. The reason(s) it stopped (multiple reasons indicate reprinted attempts): reason The lp print service can detect printer faults only through an ade- quate fast filter and (see lpfilter(ADM)) only when the standard interface program or a suitable customized interface program is used. The level of recovery after a fault depends on the capabili- ties of the filter. If the printer-name is all, the alerting defined in this command applies to all existing printers. If the -W option is not given or integer is zero (which represents once and is also the default), only one message will be sent per fault. If this command is not used to arrange fault alerting for a printer, the default procedure is to mail one message per fault to the administrator of the printer. Restrictions When creating a new printer, either the -v or the -U option must be sup- plied. In addition, only one of the following may be supplied: -e, -i, or -m; if none of these three options are supplied, the model standard is used. The -h and -l keyletters are mutually exclusive. Printer and class names may be no longer than 14 characters and must consist entirely of the characters A-Z, a-z, 0-9 and ``_'' (underscore). Removing a printer destination The second form of the lpadmin command, lpadmin -xdest, removes the des- tination dest from the lp print service. If dest is a printer and is the only member of a class, then the class will be deleted too. If dest is all, all printers and classes are removed. No other options are allowed with -x. Changing the system default destination The third form of the lpadmin command, lpadmin -d [ dest ], makes dest, an existing destination, the new system default destination. If dest is not supplied, then there is no system default destination. No other options are allowed with -d. Setting an alert for a print wheel The fourth form of the lpadmin command, lpadmin -S print-wheel -A alert- type [-W integer ] [ -Q integer ], sends the alert alert-type to the administrator as soon as the print-wheel needs to be mounted and peri- odically thereafter. The alert-types are mail Sends the alert message via mail (see mail(C)) to the administra- tor who issues this command. write Writes the message to the terminal on which the administrator is logged in. If the administrator is logged in on several termi- nals, one is chosen arbitrarily. quiet Does not send messages for the current condition. An administra- tor can use this option to temporarily stop receiving further messages about a known problem. Once the print-wheel has been mounted and subsequently unmounted, messages will again be sent when the number of print requests again exceeds the threshold. none Does not send messages until this command is given again with a different alert-type (other than quiet). shell-command The shell-command is run each time the alert needs to be sent. The shell command should expect the message as standard input. If there are blanks embedded in the command, enclose the command in quotes. Note that the mail and write values for this option are equivalent to the values mail user-name and write user-name, respectively, where user-name is the current name for the administrator. This will be the login name of the person submit- ting this command unless he or she has used the su command to change to another user ID. If the su command has been used to change the user ID, then the user-name for the new ID is used. list The type of the alert for the print wheel is displayed on the standard output. No change is made to the alert. The printers listed are those that the administrator had earlier speci- fied were candidates for this print wheel. The number (integer) listed next to each printer is the number of requests eligible for the printer. The number (integer) shown after the printer list is the total number of requests awaiting the print wheel. It will be less than the sum of the other numbers if some requests can be handled by more than one printer. If the print-wheel is all, the alerting defined in this command applies to all print wheels already defined to have an alert. Only one administrator per print wheel can be alerted. If this command is run by more than one administrator for the same print wheel, the last command run applies. If the -W option is not given or integer is 0 (which is interpreted as once and is also the default), only one message will be sent per request to mount a print wheel. If this command is not used to arrange alerting for a print wheel, no alerts will be sent for the print wheel. If the -Q option is also given, the alert will be made when integer print requests that need the print wheel are waiting. If the -Q option is not given or integer is 1 or the word any, a message is sent as soon as any- one submits a print request for the print wheel when it is not mounted. The -S option has a different meaning when used with the -p option. Defining remote printers for remote printing services The fifth form of the lpadmin command is used to define the remote print- er, printer-name2, and its machine, machine-name, that will handle remote print requests from the local machine. The remote printer will be referred to as printer-name1 on the local machine. Files /usr/spool/lp/* See also accept(ADM), enable(C), lp(C), lpfilter(ADM), lpsched(ADM), lpstat(C), stty(C) and terminfo(F). Authorization Permission to use this utility requires the lp authorization.