This chapter describes which environment variables you must set to use NQE, how to set up NQE database authorization, and how to set up NQS validation. It discusses the following topics:
NQE file structure (“NQE File Structure”)
Setting environment variables (“Setting Environment Variables”)
NQE database authorization (“NQE Database Authorization”)
NQS validation requirements (“NQS Validation Requirements”)
File validation (“File Validation”)
Password validation (“Password Validation”)
File and password validation (“File and Password Validation”)
File validation file examples (“Validation File Examples”)
Throughout this guide, the path /nqebase is used in place of the default NQE path name, which is /usr/craysoft/nqe on all systems except Solaris, UNICOS, and UNICOS/mk systems, where it is /opt/craysoft/nqe.
Figure 2-1 shows the NQE file structure.
To use NQE, you must set the following environment variables:
DISPLAY must be set to local_workstation_name:0 for the NQE graphical user interface (GUI) to work.
Note: If your site has access control in place for using X Window System applications, contact your system administrator to determine if you need additional settings. PATH must include the path name of the NQE commands. The default path name is /nqebase/bin. System administrators also must include /nqebase/etc in their PATH environment variable to use certain NQE administrator commands.
MANPATH must include the path name of the NQE man pages. The default name is /nqebase/man.
To verify whether your site's path names are the NQE system default, use the following command:
cd /nqebase/bin |
If this command is not successful, ask your system administrator where the NQE software is located and add those directories to your PATH and MANPATH environment variables.
The commands that you use to set the environment variables depend on the shell that you use. For UNICOS and UNICOS/mk systems, the standard shell (or Korn shell) is the default shell.
| Note: For UNICOS and UNICOS/mk systems, if you want to use the UNICOS module(1) interface to acquire the environment variables for NQE, check with your system administrator to see if the modules package has been installed on your system. |
For a list of other NQE environment variables that you can set to customize your environment, see “Customizing Your NQE Environment” in Chapter 9.
The following example uses sh syntax to set and display NQE environment variables:
# PATH=$PATH:/nqebase/bin:/nqebase/etc; export PATH # MANPATH=:/nqebase/man; export MANPATH # DISPLAY=snow32:0; export DISPLAY # env LOGNAME=you MAIL=/var/mail/you USER=you SHELL=/bin/sh PWD=/home/snow32/you MANPATH=:/nqebase/man PATH=/usr/bin::/nqebase/bin:/nqebase/etc DISPLAY=snow32:0 |
The following example uses csh syntax to set and display the NQE environment variables:
% setenv PATH /nqebase/bin:/nqebase/etc:$PATH % setenv MANPATH /nqebase/man:$MANPATH % setenv DISPLAY snow32:0 % env HOME=/home/snow32/you SHELL=/bin/csh TERM=xterm USER=you LOGNAME=you PWD=/home/snow32/you MANPATH=/usr/man:/opt/local/man:/nqebase/man PATH=/usr/bin:/nqebase/bin:/nqebase/etc DISPLAY=snow32:0 |
To submit or control a request or to get a status of a request in the NQE database, you must have a database user dbuser account with the proper authorization (user privileges). This database user account name can be the same as or different from your login on the client host. Your NQE administrator controls who has access to the database and from which client host.
| Note: For information about submitting your request to the NQE database, see “Submitting a Request to the NQE Database” in Chapter 4. |
If the database user name is different from your local client's login name, you must supply the database user name on each of your client requests.
| Note: The target user name of the request will still be the same as your local client login name. |
You can specify the database user name in the following ways:
Select General Options on the Configure menu of the NQE GUI Submit window and enter the name in the User Name option field.
Use the -u dbuser= command option of the cqsub, cqstatl, or cqdel command. An example follows:
cqsub -u dbuser=henry job
Set the NQEDB_USER environment variable. An example follows:
export NQEDB_USER=henry cqsub job
The following example enables jack, who is currently logged in, to become jjackson (the owner of the request) and to submit request job1 to the NQE database as Chemdept (no spaces are allowed between the comma and the name of the owner of the request):
cqsub -u dbuser=Chemdept,jjackson job1 |
For a complete description of the -u option syntax, see the cqsub(1) man page.
NQS can perform validation when you submit, monitor, delete, or send a signal to a request. Validation ensures that the user name associated with the request is authorized to submit, monitor, and control the request.
Your NQE administrator specifies the validation method used in your NQS configuration. NQS can also perform validation when the output files produced by a remotely executed request will be returned to your local system. This validation is done to ensure that the user name under which the request was executed has permission to write to your file system. Usually, the same method of validation is used for both local and remote NQS systems.
The following validation methods are possible:
File validation, which is the default method of NQS validation
Password validation
File and password validation combined
No validation is done. Your site is not likely to use this method; it is not secure and is not recommended.
To display the current method in use, you must log on to your NQS server and issue the following commands:
% qmgr Qmgr: show parameters |
The last line of this display shows the validation type:
Validation type = Validation files |
File validation is the default method of NQS validation. Validation files are checked for valid users and hosts. This check is performed at the NQS server when it receives a client request and prior to execution on the NQS server on which the request will run. NQS also checks for a validation file at your NQE client system to ensure that the user has permission to write the output files back to your system.
For remote requests to systems running the UNICOS multilevel security feature (MLS) or UNICOS/mk security enhancements, you may not be able to designate the request to be run under a different name. When these features are enabled on your system and you submit a remote request, the system might be configured to require the /etc/hosts.equiv and .rhosts files to each contain a match for the remote host and require that the remote user and local user names match.
If your site uses validation files, you must have a .rhosts or .nqshosts file in your home directory on each NQS server in the cluster that might process your request. NQS uses these files to authorize your user name before it sends your request to a batch queue.
At the NQS server, you must have an entry of the following format in one of these files:
hostname username |
The hostname is the network host name of the system from which you submit the request (the NQE client system). The username is your user name on the corresponding host.
If you have both .rhosts and .nqshosts files, NQS ignores the .rhosts file. Unless your NQE administrator gives you different advice, use the .rhosts file.
| Note: You must have a .rhosts or a .nqshosts file in your login directory on each NQS server on which your request can run. If your site uses aliases for host names, you also must include those names in the .rhosts or .nqshosts file entry. See “Using the Same User Name When Submitting a Request to NQS_SERVER on a Multiple-node NQE Using the NLB”, and “Using an Alternative User Name When Submitting a Request to NQS_SERVER on a Multiple-node NQE Using the NLB”, for information about entries in the .rhosts file or .nqshosts file. |
If your site uses aliases for host names, you also must include those names in the file, as in the following example:
snow jane snow.site.com jane |
If your site uses password validation, you must supply a password each time you submit, monitor, delete, or send a signal to a request. The password cannot contain more than 8 characters. To ensure that you will be prompted for your password, use one of the following (the password you supply is for the user name under which the request will execute):
If you use the NQE GUI, select Set Password on the Actions menu of the Submit window; enter and "apply" your password.
If you use the command line interface, specify the -P option when you use the cqsub, cqstatl, and cqdel client commands.
Set the NQS_PASSWORD_NEEDED environment variable.
When you are prompted for your password, you supply the password for the user name at the NQS server on which the request will execute.
The NQE client sends the password in an encrypted form to the NQS server when it sends the request. Before the request is executed, the password is checked at the NQS server. If the password is not valid, the request is rejected.
Note: NQS does not use password validation when sending output files between two NQS systems.
If you use the NQE GUI, you do not need to set a password. The validation file is then checked. If you do not supply a password, NQS checks your validation files. If you supply a password (whether correctly or incorrectly), NQS checks only the password and not the file.
This section describes the following possible scenarios for validation files, as follows:
Using the same user name when submitting a request on a single-node NQE (“Using the Same User Name When Submitting a Request on a Single-node NQE”)
Using the same user name when submitting a request to the NQE database on a multiple-node NQE (“Using the Same User Name When Submitting a Request to the NQE Database on a Multiple-node NQE”)
Using the same user name when submitting a request to NQS_SERVER on a multiple-node NQE using the NLB (“Using the Same User Name When Submitting a Request to NQS_SERVER on a Multiple-node NQE Using the NLB”)
Using an alternative user name when submitting a request to the NQE database on a multiple-node NQE (“Using an Alternative User Name When Submitting a Request to the NQE Database on a Multiple-node NQE”)
Using an alternative user name when submitting a request to NQS_SERVER on a multiple-node NQE using the NLB (“Using an Alternative User Name When Submitting a Request to NQS_SERVER on a Multiple-node NQE Using the NLB”)
In this example, snow, frost, and hail are clients submitting requests to rain. rain is the only NQE node in this NQE cluster. User jane is using the client commands or the NQE GUI on her workstation called snow. jane wants to submit her job request to NQS or to the NQE database, both of which reside on the NQE node called rain.
At a minimum, jane must have the following:
Access to an account (a login ID) on her workstation (snow).
Access to an account on the NQE node rain.
jane will be submitting requests to rain from client snow only, not from clients frost or hail. (User jane on the client workstations on frost or hail can be someone else who is also named jane.) For NQS on rain to accept her requests, jane must have a .nqshosts or .rhosts file in her login directory on rain with the following entry:
snow jane
jane will be receiving output files on snow; therefore, she must have the file ~jane/.rhosts on snow with the following entry specifying that jane at rain is allowed remote access:
rain jane
Because jane also wants to submit requests to the NQE database, she must have authentication on the NQE database (see “NQE Database Authorization”).
Job output will be returned from the NQS server by default to the NQE client, snow, by either FTA or rcp. FTA will be attempted first.
FTA may require a password for the destination host (NQE client snow) and user (user jane at snow), which can be supplied by creating a .netrc file in the login directory of user jane on rain (~jane/.netrc on rain). (For further information, see the netrc(5) man page).
FTA can also be configured so that jane will not have to supply a password. This configuration in FTA is called network peer-to-peer authorization (NPPA). Check with your system administrator to see if this option is available.
rcp is used only to return output if FTA fails immediately to return the output. rcp requires a .rhosts file at the destination host in the recipient's home directory (~jane/.rhosts on snow).
NQS will always try to use your .nqshosts file and will use the .rhosts file only if the .nqshosts file does not exist. You should use .rhosts files unless your system administrator tells you that you should not use them.
Once she has her .rhosts files in place, jane can submit requests to rain. For example, jane could submit the request named testjob by using either the NQE GUI or the command line interface. If she uses the command line interface, she would enter the following command; the value for dest_type can be nqedb (to send a request to the NQE database) or nqs (to send a request to NQS):
cqsub -d dest_type testjob |
For more information about using the cqsub -d option, see Chapter 4, “Submitting Requests”, or the cqsub(1) man page.
In this example, user jane is using the NQE GUI or NQE client commands on workstation snow. The NQE database resides on wind. User jane wants to submit requests to the NQE database on wind, where the NQE scheduler will select a target system. To submit requests to the NQE database on wind, jane must have authentication on the NQE database (see “NQE Database Authorization”).
In this example, three other NQE nodes exist in the NQE cluster that have the names gust, storm, and rain. This means that jane can potentially run requests on rain, gust, storm, and wind. To use all four nodes, jane must have a .rhosts (or .nqshosts) file in her home directory on each of the four nodes.
Since jane uses the same login ID on all of the NQE nodes, the .rhosts file on snow would contain the following entries:
On the NQE client workstation snow:
rain jane (lets [email protected] return output to snow)
gust jane (lets [email protected] return output to snow)
storm jane (lets [email protected] return output to snow)
wind jane (lets [email protected] return output to snow)
Note: This is required only if rcp is the output mechanism; also, these entries need to be in the .rhosts file. rcp does not use the .nqshosts file.
The .rhosts file for user jane on each NQE node must contain the following entry (note that it is the same entry on each NQE node):
On node wind:
snow jane (permits incoming requests from [email protected])
On node gust:
snow jane (permits incoming requests from [email protected])
On node rain:
snow jane (permits incoming requests from [email protected])
On node storm:
snow jane (permits incoming requests from [email protected])
Once she has her .rhosts files in place, jane can submit requests to wind. For example, jane could submit the request named testjob by using either the NQE GUI or the command line interface. If she uses the command line interface, she would enter the following command:
cqsub -d nqedb testjob |
Once a target system is selected, the LWS on that node authenticates user jane.
Job output will be returned from the NQS server by default to the NQE client, snow, by either FTA or rcp. FTA will be attempted first.
FTA may require a password for the destination host (NQE client snow) and user (user jane at snow), which can be supplied by creating a .netrc file in the login directory of user jane on wind (~jane/.netrc on wind) (if it is executed there). (For further information, see the netrc(5) man page).
FTA can also be configured so that jane will not have to supply a password. This configuration in FTA is called network peer-to-peer authorization (NPPA). Check with your system administrator to see if this option is available.
rcp is used only to return output if FTA fails immediately to return the output. rcp requires a .rhosts file at the destination host in the recipient's home directory (~jane/.rhosts on snow).
NQS will always try to use your .nqshosts file and will use the .rhosts file only if the .nqshosts file does not exist. You should use .rhosts files unless your system administrator tells you that you should not use them.
Figure 2-2 shows how the file validation scenario looks:
In this example, user jane is using the NQE GUI or NQE client commands on workstation snow and her NQS server is rain (NQS_SERVER=rain).
User jane wants to submit requests to rain, using load balancing (NLB) to select a target system.
In this example, three other NQS server nodes exist in the NQE cluster that have the names gust, storm, and wind. This means that jane can potentially run requests on rain, gust, storm, and wind. To use all four nodes, jane must have entries in a .rhosts (or .nqshosts) file in her home directory on each of the four nodes. Assuming that jane uses the same login ID on all of the four nodes, the .rhosts files would contain the following entries:
On the NQE client workstation snow:
rain jane (lets [email protected] return output to snow)
gust jane (lets [email protected] return output to snow)
storm jane (lets [email protected] return output to snow)
wind jane (lets [email protected] return output to snow)
Note: This is required only if rcp is the output mechanism; also, these entries need to be in the .rhosts file. rcp does not use the .nqshosts file. On node rain:
snow jane (permits incoming requests)
On node gust:
rain jane (accepts requests from rain)
On node wind:
rain jane (accepts requests from rain)
On node storm:
rain jane (accepts requests from rain)
Once she has her .rhosts files in place, jane can submit requests to her NQS_SERVER rain. For example, jane could submit the request named testjob by using either the NQE GUI or the command line interface. If she uses the command line interface, she would enter the following command:
cqsub -d nqs testjob |
Job output will be returned from the NQS server by default to the NQE client, snow, by either FTA or rcp. FTA will be attempted first.
FTA may require a password for the destination host (NQE client snow) and user (user jane at snow), which can be supplied by creating a .netrc file in the login directory of user jane on rain (~jane/.netrc on rain) (if it is executed there). (For further information, see the netrc(5) man page.)
FTA can also be configured so that jane will not have to supply a password. This configuration in FTA is called network peer-to-peer authorization (NPPA). Check with your system administrator to see if this option is available.
rcp is used only to return output if FTA fails immediately to return the output. rcp requires a .rhosts file at the destination host in the recipient's home directory (~jane/.rhosts on snow).
NQS will always try to use your .nqshosts file and will use the .rhosts file only if the .nqshosts file does not exist. You should use .rhosts files unless your system administrator tells you that you should not use them.
Figure 2-3 shows how the file validation scenario looks:
By default, NQE expects that you have the same user name on all of your NQE nodes. However, you can submit requests to execute under an alternative user name.
In this example, user jane is using the NQE GUI or NQE client commands on workstation snow. The NQE database resides on wind. User jane wants to submit requests to the NQE database on wind as user fred. The NQE scheduler will select a target system.
In this example, three other NQE nodes exist in the NQE cluster that have the names gust, storm, and rain.
For jane to use all four NQE nodes as user fred, user fred must permit jane to execute under his account, so fred must have a .rhosts file in his home directory on each of the four nodes.
By default, job output will be returned from the NQS server to the workstation host, snow, by either FTA or rcp. (FTA is the default.) User jane must allow fred to return output to her at the workstation host, snow. User fred must have write permission to the directory in which the output is returned.
On the NQE client workstation snow, ~jane/.rhosts would contain:
rain fred (lets rain return output to snow)
gust fred (lets gust return output to snow)
storm fred (lets storm return output to snow)
wind fred (lets wind return output to snow)
Note: These entries are required only if rcp is the output mechanism; also, these entries need to be in the .rhosts file. rcp does not use the .nqshosts file.
On the NQE nodes, fred must have the following entry in his .rhosts file (note that it is the same entry on each NQE node):
On the NQE database node wind, ~fred/.rhosts would contain:
snow jane (permits incoming requests)
On node gust, ~fred/.rhosts would contain:
snow jane (permits incoming requests)
On node rain, ~fred/.rhosts would contain:
snow jane (permits incoming requests)
On node storm, ~fred/.rhosts would contain:
snow jane (permits incoming requests)
Once the .rhosts files are in place, jane can submit a request to the NQE database as fred. For example, jane could submit the request named testjob as user fred by using either the NQE GUI or the command line interface. If she uses the command line interface, she would enter the following command:
cqsub -d nqedb -u fred testjob |
Once a target system is selected, the LWS on that node authenticates user jane.
FTA may require a password for the destination host (NQE client snow) and user (user jane at host snow), which can be supplied by creating a .netrc file in the login directory of user jane on host wind (~jane/.netrc on wind). (For further information, see the netrc(5) man page).
In this example of alternative user names, the job request ran as user fred and it will be user fred trying to return the output back to user jane on host snow. The .netrc file must then be in ~fred/.netrc on rain (if it is executed there) and contain jane's password on snow.
FTA can also be configured so that jane will not have to supply a password. This configuration in FTA is called network peer-to-peer authorization (NPPA). Check with your system administrator to see if this option is available.
rcp is used only to return output if FTA fails immediately to return the output. rcp requires a .rhosts file at the destination host in the recipient's home directory (~jane/.rhosts on host snow).
Figure 2-4 shows how the file validation scenario looks:
Figure 2-4. Submitting Request to the NQE Database on Multiple-node NQE Using an Alternative User Name
By default, NQE expects that you have the same user name on your workstation as on your NQS server node. However, you can submit requests to execute under an alternative user name.
In this example, user jane is using the NQE GUI or NQE client commands on workstation snow and her NQS_SERVER is rain. User jane wants to submit requests to NQS_SERVER rain as user fred.
In this example, three other NQE nodes exist in the NQE cluster that have the names gust, storm, and wind.
For jane to use all four NQE nodes as user fred, user fred must permit jane to execute under his account, so fred must have a .rhosts file in his home directory on each of the four nodes.
By default, job output will be returned from the NQS server to the workstation host, snow, by either FTA or rcp. (FTA is the default.) User jane must allow fred to return output to her at the workstation host, snow. User fred must have write permission to the directory in which the output is returned.
On the NQE client workstation snow, ~jane/.rhosts would contain:
rain fred (lets rain return output to snow)
gust fred (lets gust return output to snow)
storm fred (lets storm return output to snow)
wind fred (lets wind return output to snow)
Note: These entries are required only if rcp is the output mechanism; also, these entries need to be in the .rhosts file. rcp does not use the .nqshosts file. By default, on rain, user jane must have an account to permit the incoming request, and user fred must permit jane to execute under his account. To allow this to occur, the following is required by NQS on rain:
~jane/.rhosts: snow jane
~fred/.rhosts: rain jane
On node gust, ~fred/.rhosts must contain:
rain fred (accepts requests from rain)
On node wind, ~fred/.rhosts must contain:
rain fred (accepts requests from rain)
On node storm, ~fred/.rhosts must contain:
rain fred (accepts requests from rain)
Once the .rhosts files are in place, jane can submit a request to her NQS_SERVER rain as fred. For example, jane could submit the request named testjob as user fred by using either the NQE GUI or the command line interface. If she uses the command line interface, she would enter the following command:
cqsub -d nqs -u fred testjob |
FTA may require a password for the destination host (NQE client snow) and user (user jane at host snow), which can be supplied by creating a .netrc file in the login directory of user jane on host rain (~jane/.netrc on rain). (For further information, see the netrc(5) man page.)
In this example of alternative user names, the job request ran as user fred and it will be user fred trying to return the output back to user jane on host snow. The .netrc file must then be in ~fred/.netrc on rain (if it is executed there) and contain jane's password on snow.
FTA can also be configured so that jane will not have to supply a password. This configuration in FTA is called network peer-to-peer authorization (NPPA). Check with your system administrator to see if this option is available.
rcp is used only to return output if FTA fails immediately to return the output. rcp requires a .rhosts file at the destination host in the recipient's home directory (~jane/.rhosts on host snow).
Figure 2-5 shows how the file validation scenario looks:
