5    Creating and Managing Servers

This chapter describes how to create and manage Advanced Printing Software spoolers and supervisors. The chapter is divided into the following sections:

NOTE

The Advanced Printing Software Administrator Utilities subset includes the script, pd_get_started, that simplifies the task of creating server databases. You can use either the pd_get_started script or the utilities described in this chapter to create server databases.

5.1    Creating Servers

One of the initial steps to configuring a print system is to create a supervisor and a spooler. These servers control the flow of print jobs submitted by users. That is, the supervisor and spooler receive jobs submitted by users, submit the print data to printers, and send and receive control and status information between the printers and users.

Each print system server process has a database associated with it. This database contains the configuration attributes of the server.

Creating a running server process consists of two steps:

  1. Creating the object database for the server.

  2. Starting the server.

5.1.1    Creating an Object Database

Use the pdmakedb command to create an object database. You must create an object database before you can start the server process.

The pdmakedb command creates an object database that initially contains a single object, the corresponding server object. The name of the database is also the name of the server object. Note the -n option. The command adds default attributes to the server object, plus any attributes you specify by using the options.

If the database you specify already exists, the pdmakedb command displays an error message and exits.

The pdmakedb command has the following command-line syntax::

pdmakedb [-A adminACL] [- h] [-nserverName] [-s spoolDir] [- t serverType]

-A adminACL

Specifies the access control list (ACL ) for the server. The default is name group.

-h

Prints a list of the supported options.

-n serverName

Specifies the name of the object database as well as the corresponding server.

If you do not specify a server name, the default name for the server is hostName_spl for a spooler and hostName_sup for a supervisor.

-s spoolDir

Specifies the location where the server spools documents to be printed. The spool directory can be any valid UNIX directory pathname. The default is /var/spool/pd/serverName. serverName is as specified with the -n option.

-t serverType

Specifies the type of object database, spooler or supervisor. The valid values for serverType are: SPL for a spooler and SUP for a supervisor.

-v

Prints messages as it validates attributes provided on the command line.

The pdmakedb command provides a default value for any option that you do not specify on the command line. The following examples show how to use pdmakedb to create spoolers and supervisors. You must create object databases from the root account. When you need to add users to the ACL, you can use the methods described in the Section 4.3 of this book.

The following examples demonstrate use of the pdmakedb command:

Issuing the previous commands results in the creation of server databases blue_sup, blue_spl, and blue_obg.

5.1.2    Displaying Object Database Data

Use the pdshowdb command to display the values of all attributes currently set on the server object. The attributes displayed include both configuration and nonconfiguration attributes, and internal as well as user-visible attributes. The command does not change the object database in any way.

The format that pdshowdb uses to display the server object attributes is the same format used by pdmakedb and pdmoddb with the -voption set.

The pdshowdb command has the following command-line syntax:

pdshowdb [-e] [-h] [-n serverName]

-e

Displays the absolute path of the executable file used to start the server.

-h

Displays a list of the supported options.

-n serverName

Specifies the name of the object database and the corresponding server.

5.1.3    Modifying an Existing Object Database

Use the pdmoddb command to modify an existing object database. This command modifies the attributes you specify on the command line if the attribute already exists in the database. If the specified attribute does not exist, the pdmoddb command creates the attribute and assigns the specified value. The command also adds any default attributes that do not already exist and that you do not specify on the command line.

The pdmoddb command cannot be used to modify a database that is in use by an operating server. The server must be shut down before pdmoddb can access the database file.

The pdmoddb command displays an error message and exits if the database you specify does not exist or is in use.

The pdmoddb command has the following command-line syntax:

pdmoddb [-A adminACL] [- h] [-nserverName] [-s spoolDIR] [- t serverType]

-A adminACL

Specifies the access control list (ACL) for the server. The default is name group.

-h

Displays a list of the supported options.

-n serverName

Specifies the name of the object database as well as the corresponding server.

-s spoolDir

Specifies the location where the server spools documents to be printed. The spool directory spoolDir can be any valid UNIX directory pathname. The default is /var/spool/pd/serverName ServerName is as specified with the -n option.

-t serverType

Specifies the type of object database, SPL or SUP.

-v

Prints messages as it validates attributes provided on the command line.

5.1.4    Backing Up Object Databases

You should make routine backups of your print system object databases to protect against inadvertent data loss or data corruption. If a failure occurs and your object databases become inaccessible or corrupt, you can restore the system from a recent backup and avoid the need to recreate your print system environment from scratch.

You should consider backing up the following areas:

Server databases should be backed up when the servers are not running. This ensures that the backup copies are internally consistent. Routine backups can be performed at a time of day or week when the print system can be temporarily shut down for the duration of the backup.

5.2    Configuring Server Object Attributes

A number of server object attributes can be set or modified. Table 5-1 lists the attributes and describes what effect they have on the server.

Table 5-1:  Server Object Attributes

Attributes Description
access-control-list Specifies the authorized users of the spooler or supervisor.
descriptor A text string describing the server.
job-attributes-visibable-to-all Lists job and documentation attributes that are visible to nonowners of the job with the pdls and pdq commands.
message A test string indicating the sate of the server.
notification-profile Specifies the events for users notification and specifies the notification method.
job-completion-period Specifies the amount of time the spooler maintains job objects after jobs are completed and retained. This is different from job retention because the document files are not kept. When the retention period is over and the completion period has begun, a job can not be resubmitted for re-print
hold-jobs-interrupted-by-printer-failure Specifies whether jobs returned to the spooler after a restart should be put in the hold or pending state.
filter-definition Defines one or more translation or modification filters supported by the supervisor and defines how the filter is invoked. If you intend to print text documents on a PostScript printer, then you need to set up the text-to-PostScript translation filter, as described in Section 8.2
   

5.2.1    Examples of Setting Server Object Attributes

The following examples show how to set some of the more common server attributes for spoolers and supervisors.

5.3    Configuring Servers in a TruCluster Server Environment

Spoolers and supervisors (servers) can be configured to run as highly available, single-instance applications in a TruCluster Server environment. A single-instance application is one that is installed, configured, and run on only one member of a cluster but can be seen on all members of the cluster.

A highly available server is configured using the TruCluster Server cluster application availability (CAA) subsystem. CAA monitors the resources required by the server in a cluster and ensures that they run on a cluster member that meets these resource needs. If the cluster member that the server is running on fails or if a required resource fails, CAA relocates or "fails over" the server to another member that has the required resources.

To configure and run servers as a highly available, single-instance applications, you need:

Each of these items is described in the following sections. See the TruCluster Server Highly Available Applications manual for more information.

5.3.1    apx-default.cap Resource Profile

A resource profile defines how an application is started, managed, and monitored by CAA.

When the Advanced Printing Software server subset (APXSVRxxx) is configured, the configuration script determines if TruCluster software is installed on the system. When the TruCluster Server software is detected, the configuration script installs the apx-default.cap CAA resource profile in the /var/cluster/caa/profile directory. This is the resource profile representing servers and supervisors that are created in your print environment. Any spooler or supervisor that you create is placed in the apx-default resource. You can create additional resource profiles and move spoolers and supervisors from the apx-default resource profile into them.

5.3.2    apx-default.scr Action Script

An action script specifies how to start the application, how to stop the application and the clean up that occurs before the application fails over, and how to check the application to see if it is still running.

During the Advanced Printing Software installation when the TruCluster Server software is detected, the installation process installs the /var/cluster/caa/script/apx-default.scr action script.

5.3.3    Registering the apx-default Resource Profile

After the resource profile and the action script are in place, you must register the resource profile with CAA.. Use the caa_register command to register the apx-default resource profile:

# /usr/sbin/caa_register apx-default

Once you have registered this CAA resource profile, you should use CAA commands to start and shut down the servers. Do not use the pdsplr, pdspvr, or pdshutdown commands.

5.3.4    Starting and Stopping the Resource Profile

After you register apx-default with CAA, you can start the resource profile using the caa_start command:

# /usr/sbin/caa_start apx-default

When the resource starts, a message similar to the following is displayed:

Attempting to start `apx-default` on member `membername`
Start of `apx-default` on member `membername` succeeded.
 

To stop the application, you use the caa_stop command:

# /usr/sbin/caa_stop apx-default

5.3.5    Adding Servers to the apx-default Resource Profile

After the initial servers are running in the cluster environment, you might need to add additional spoolers and supervisors to the resource profile. To add servers to the default resource, first you create and start the spoolers and supervisors that you want to add. You can use the /usr/pd/scripts/pd_get_started script or the pdmakedb, pdsplr, and pdspvr commands. When the new server is created, it becomes a part of the apx-default resource profile.

5.3.6    Customizing the Advanced Printing Cluster Environment

You can customize your CAA print environment by relocating resource profiles, creating new resource profiles, and modifying and deleting resource profiles. The following subsections describe these topics.

5.3.6.1    Relocating Resources

When you relocate a resource profile, you move the resource from one cluster member to another cluster member. Use the caa_relocate command. to relocate a resource profile. You can specify which cluster member you want to relocate the resource profile to, or allow CAA to identify an available member. When you relocate a resource profile, the associated servers are are shut down and then restarted on the new member.

The following examples show how to use the caa_relocate command to relocate a resource profile:

5.3.6.2    Using the apx_caa_setup Script to Manage CAA Resource Profiles

Use the apx_caa_setup script to customize your CAA print environment. This script is located in the /usr/pd/cluster directory and allows you to:

The following shows the main menu of the apx_caa_setup script:

  Advanced Printing Software Cluster Setup
 
                        *** MAIN MENU ***
 
            1  Display CAA printing resources
 
            2  Create CAA printing resource
 
            3  Modify CAA printing resource
 
            4  Delete CAA printing resource
 
            5  Initialize CAA resources for Advanced Printing
 
            6  Exit
 
Enter the number that corresponds to your choice:[6]

5.3.6.2.1    Displaying CAA Printing Resource Profiles

The Display CAA printing resources function allows you to view all of the CAA resources for the Advanced Printing environment. The apx-default resource is shown as well as any resource profiles you have created. Each resource contains a list of the servers that are part of the resource profile.

Enter the number that corresponds to your choice:[6] 1
 
    Currently defined Advanced Printing CAA Resources
 
     1  mikes: green_spl green_sup 
     2  robs: rob_spl rob_sup
     3  orange: orange_spl orange_sup
     4  BLExit: root_sup root_spl
     5  blue: blue_sup blue_spl
 
        apx-default: daffy_spl daffy_sup

5.3.6.2.2    Creating a CAA Printing Resource Profile

When you create a CAA resource profile using the apx_caa_setup script, the resource profile is created, you are asked which spoolers and supervisors you want associated with the resource profile, and the resource profile is registered with CAA. Server processes can be associated with only one CAA resource profile. Therefore, when you specify spoolers or supervisors to be associated with a resource profile, you effectively remove those spoolers or supervisors from the apx-default resource profile. A sample output of this process follows:

Enter the number that corresponds to your choice:[6] 2
 
    Currently defined Advanced Printing CAA Resources
 
     1  mikes: green_spl green_sup     
     2  robs: rob_spl rob_sup
     3  orange: orange_spl orange_sup
     4  BLExit: root_sup root_spl
     5  blue: blue_sup blue_spl
 
        apx-default: daffy_spl daffy_sup
 
Enter a unique name for the new CAA resource: resourceX
 
Enter the names of one or more Advanced Printing spooler
or supervisors to be associated with the resource "resourceX":
 
  resourceX: orange_sup orange_spl
 
  Creating /var/cluster/caa/script/resourceX.scr ... 
  Creating /var/cluster/caa/profile/resourceX.cap ...
  Registering resourceX with CAA...

5.3.6.2.3    Modifying a CAA Printing Resource Profile

Use the apx_caa_setup script to modify the servers governed by a CAA printing resource profile. When you modify a resource profile, you are adding or removing servers from the resource profile. If you remove a server from a resource profile, the server is placed in the apx-default resource profile.

The following example shows how to add two servers, blue_sup and blue_spl, to the CAA printing resource orange. Note that servers orange_spl and orange_sup were originally associated with the resource, but must be reentered in the list of servers associated with the modified CAA resource orange. If you do not reenter the original servers, they will be returned to the apx-default resource profile.

Enter the number that corresponds to your choice:[6] 3
 
    Currently defined Advanced Printing CAA Resources
 
     1  mikes: green_spl green_sup
     2  robs: rob_spl rob_sup
     3  orange: orange_spl orange_sup
     4  BLExit: root_sup root_spl
     5  blue: blue_sup blue_spl
     6  apx_orange: orange_sup orange_spl
 
        apx-default: daffy_spl daffy_sup
 
Modify which resource? 3
Modify CAA map entry "orange"? ([y]/n)
 
Enter the names of one or more Advanced Printing spooler
or supervisors to be associated with the resource "orange":
 
  orange: orange_spl orange_sup blue_spl blue_sup
  Modifying resource orange...

5.3.6.2.4    Deleting a CAA Printing Resource Profile

When you delete a CAA printing resource profile using the apx_caa_setup script, the resource profile is stopped and unregistered, and the action script and resource profile are deleted.

5.3.6.2.5    Initializing CAA Printing Resource Profiles

Initializing CAA printing resources allows you to set-up CAA on a system that was not a cluster member when you installed Advanced Printing Software.

When you initialize the CAA printing resources, the following tasks are performed:

The following example shows the output displayed during the initialization:

Enter the number that corresponds to your choice:[6] 5
 
The Advanced Printing CAA map file already exists.
This option performs the following tasks:
 
  - Disassociates all Advanced Printing spoolers and
    supervisors from named CAA resources.
 
  - Stops and unregisters printing resources, but leaves
    spoolers and supervisors running.
 
  - Deletes resource profiles and action scripts associated
    with printing resources defined in the
    /var/pd/config/apx_caa_map.conf file.
 
  - Creates a new, empty /var/pd/config/apx_caa_map.conf file.
 
  - Registers the apx-default resource.
    Do you want to initialize anyway? (y/[n])

5.3.7    Configuring a Printer to Run on One Member

Some printers are directly connected to the serial or parallel port of a host. These printers must be controlled by a supervisor running on that host. To ensure that the supervisor runs on the correct cluster member, you must create a separate CAA resource profile for the supervisor. The resource profile must specify:

After you create the physical printer object, set the printer-associated-host attribute to the name of the host to which the printer is connected.

# pdset -c printer -x printer-associated-host=hostname  printername

In addition, the supervisor that is associated with the printer, must be running on the host that the printer is restricted to.

If a job is sent to the printer from a supervisor running on a host other than the one specified by the printer-associated-host attribute, the supervisor disables the physical printer and sets the following attributes:

5.3.8    LPD Inbound Gateway in a Cluster

The LPD Inbound Gateway is not configured as a CAA application but is run on each member of the cluster. To configure the LPD Inbound Gateway, run the /usr/pd/scripts/inbound_gw_config.sh script. This script configures the LPD Inbound Gateway on each member of the cluster and edits the rc.config file so that each time your system restarts, the LPD Inbound Gateway restarts.

The /sbin/init.d/apx start and /sbin/init.d/apx stop commands start and stop the LPD Inbound Gateway.

5.4    Managing Servers

This section describes the administrative tasks that you perform on spoolers and supervisors. These tasks include starting and stopping, pausing and resuming, enabling and disabling, and possibly deleting servers.

5.4.1    Server States

The server attributes server-state and enabled determine the state of a server process. The server process can be in one of the following states:

While server-state can be set to ready, if the server is disabled, it will not receive print jobs.

Use the following command line to determine the state of a server, in this case blue_sup:

# pdls -c server blue_sup

The default for this command returns both the server-state and the enabled attributes:

server-name server-state enabled
----------- ------------ ------------
blue_sup    ready        yes 

5.4.2    Starting a Server

Starting a server consists of running an appropriate executable file for the server type. The startup syntax represents a string that you can type at a shell prompt. Generally, however, you will start servers by way of a shell script, and the host will execute the startup syntax from within the shell script. The shell script could be part of the startup script that you create or the one that executes normally when the UNIX system boots, such as the file /sbin/init.d/apx or a CAA action script.

A print system server behaves like a UNIX daemon. It starts up at boot time by way of a shell script without user input. Like typical UNIX daemons, the server starts up in the background and runs relative to a runtime directory. When you start a spooler or supervisor, you must do so from the root account.

5.4.3    Starting a Spooler

The command syntax for starting a print system spooler is:

/usr/pd/lib/pdsplr [-a] [-c] [-d ODBpath] [-e emailAddress] [serverName]

-a

Rquired only for server startups taking place after the server had to repair the object database as part of a crash recovery.

-c

Forces a database integrity check at startup after a normal shutdown. (The server automatically checks the database integrity when it restarts after a crash.)

-d ODBpath

Specifies the location of the object database files. The server requires a server name on startup so that it can locate its object database. By default, the server assumes that the object database resides in a standard location for all server object databases (/var/pd/odb).

-e emailAddress

Specifies an e-mail address that should receive notification of server startup errors.

If you do not specify an e-mail address, server startup errors are reported to standard error and to syslog.

/usr/pd/lib/pdsplr -e someuser@somesystem.com myserver

The following examples show how to use the pdsplr command to start a spooler:

5.4.4    Starting a Supervisor

The command syntax for starting a print system supervisor is:

/usr/pd/lib/pdspvr [-a] [-c] [-d ODBpath] [-e emailAddress] [serverName]

-a

Required option for a server startup taking place after the server had to repair the object database as part of a crash recovery.

-c

Forces a database integrity check at startup after a normal shutdown. You might want to use the -c option if you suspect that the database is corrupt. (The server automatically checks the database integrity when it restarts after a crash.)

-e emailAddress

Specifies an e-mail address that should receive notification of server startup errors. If you do not specify an e-mail address, server startup errors are reported to standard error and to syslog.

5.4.5    Starting an Outbound Gatway Supervisor

The options for starting an Outbound Gateway Supervisor arethe same as that of the supervisor, but the command executable is different. To start an Outbound Gateway Supervisor use the following command:

#/usr/pd/lib/pdspvlpr server_name

The following examples show use of the pdspvr and pdspvlpr commands to start supervisors:

5.4.6    Enabling a Server

After initially creating and starting a server, you must enable the server so that it is available for use.

pdenable -c server[-m message_txt]server_name

-m message text

Allows you to include a message when the server is enabled. The message can be retrieved with a pdls command.

The following example shows how to use the pdenable command to enable a spooler (red_spl):

# pdenable -c server red_spl

5.4.7    Disabling a Server

Use the pddisable command to disable a server.

When a spooler is disabled, all previously submitted jobs are scheduled and delivered to physical printers, while all requests for new jobs are rejected.

When a supervisor is disabled, jobs that are being processed by the supervisor are completed, and all new jobs are rejected.

The pddisable command has the following syntax:

pddisable [-c class_name] [-m message_txt] [-x extended_attribute_string] [-X attribute_filename] server_name

-c class_name

Specifies the class or type of object you are disabling. In this case class is server.

-m message_text

Allows you to include a message that can be retrieved with a pdls command.

-x extended_attribute_string

Specifies one or more attribute type=value pairs that are set when the pddisable command executes.

-X attribute_filename

Use this option to specify a file name that contains a series of attribute type=value pairs that are set when the pddisable command executes.

The following example shows how to use the pddisable command to disable the spooler, red_spl:

# pddisable -c server red_spl

5.4.8    Removing Jobs from a Server

There are two commands available to remove jobs from a server; pddelete and pdclean.

The pdclean command removes all jobs on a server.

The pddelete command removes one or more named jobs from a server.

5.4.8.1    Removing Named Jobs from a Server

Use the pddelete command to delete one or more named jobs from a server.

pddelete -c job job_id

The following example shows how to use the pddelete command:

Delete job 155 on spooler blue_spl:

# pddelete -c job blue_spl:155

5.4.8.2    Removing All Jobs from a Spooler

The pdclean command removes all jobs from a spooler. Consider the following when using pdclean to remove jobs from a spooler.

The pdclean command has the following syntax:

pdclean -c server [-m message_txt] server_name

-m message_txt

Sets the server message text. Users can view the message with the pdls command.

The following example shows how to use the pdclean command to remove all jobs from red_spl:

# pdclean -c server red_spl

5.4.9    Pausing Spoolers

Use the pdpause command to pause a spooler. A supervisor cannot be paused. When a spooler is paused, it will not submit jobs to supervisors, but the logical printers associated with the spooler continue to accept new jobs.

The pdpause command has the following syntax:

pdpause -c server [-m message_txt] [-x extended_attribute_string] [-X attribute_filename] server_name

-m message_txt

Allows you to include a message when the server is paused. The message can be read with the pdls command.

-x extended_attribute_string

Specifies a series of attribute type=value pairs that are set when the pdpause command executes.

-X attribute_filename

Specifies a file that contains a series of attribute type=value pairs that are set when the pdpause command executes.

The following example shows how to use the pdpause command to pause a spooler ( red_spl):

# pdpause -c server red_spl

5.4.10    Resuming a Server

Use the pdresume command to restart operation of a spooler that has been paused by the pdpause command. The syntax of the pdresume command is:

pdresume -c server [-m message_txt] [-x extended_attribute_string] [-X attribute_filename] server_name

-m message text

Allows you to include a message when the server operation is resumed. The message is retrieved with the pdls command.

The following example shows how to use the pdresume command to resume a spooler and set the server message:

# pdresume -c server \
-m "Spooler operation resumed at 13:00" red_spl

5.4.11    Shutting Down a Server

Use the pdshutdown command to shut down a server process. Both spoolers and supervisors disable themselves when this command is issued and then shut down by the method specified by the value of the when_time option.

The shut down operation is asynchronous. Do not use pdshutdown in scripts unless the scripts use other commands to monitor the commands progress.

pdshutdown -c server [-w when_time] [-x extended_attribute_string] [-X attribute_filename] server_name

-w when_time

Specifies how much processing can occur before the server is shut down. The following arguments are allowed:

The following example shows how to use the pdshutdown command to shutdown a spooler after all currently printing jobs are completed:

#pdshutdown red_spl

5.4.12    Deleting a Server

Use the pddelete command to delete a server. When you delete a server, you should consider the following:

If the server is a spooler:

If the server is a supervisor:

The pddelete command has the following syntax:

pddelete -c server server_name

The following examples show how to use the pddelete command to delete a server: