You can transfer files between remote systems on a network either from within a batch request or interactively by using the NQE File Transfer Agent (FTA). The ftua and rft commands transfer files. The ftua interface to FTA is similar to the TCP/IP ftp utility. File transfers can be initiated only on NQE nodes.
This chapter discusses the following topics:
File transfer terms (“File Transfer Terms”)
Using ftua
Selecting a domain (“Selecting a Domain”)
Connecting to a remote host (“Connecting to a Remote Host”)
Selecting a mode (“Selecting a Mode”)
Specifying the type of file to transfer (“Specifying the Type of File to Transfer”)
Copying files from a host (“Copying Files from a Host”)
Copying files to a host (“Copying Files to a Host”)
Copying multiple files (“Copying Multiple Files”)
Copying files to and from IBM MVS systems (“Copying Files to and from IBM MVS Systems”)
Appending files (“Appending Files”)
Deleting files (“Deleting Files”)
Displaying queued transfers (“Displaying Queued Transfers”)
Aborting transfers (“Aborting Transfers”)
Waiting for transfer requests (“Waiting for Transfer Requests”)
Closing a connection or ending a session (“Closing a Connection or Ending a Session”)
ftua examples (“ftua Examples”)
macdef example (“macdef Example”)
Transferring files from within a request file (“Transferring Files from within a Request File”)
Using ftua with the UNICOS multilevel security (MLS) feature or UNICOS/mk security enhancements (“Using ftua with the UNICOS Multilevel Security (MLS) Feature or UNICOS/mk Security Enhancements”)
File naming conventions (“File Naming Conventions”)
Failure notification (“Failure Notification”)
Using rft (“Using rft”)
Using autologin (“Using Autologin”)
Creating .netrc file entries (“Creating .netrc File Entries”)
.netrc file example (“.netrc File Example”)
Using NPPA (“Using NPPA”)
For a complete description of the ftua commands, see the ftua(1) man page.
For a complete description of the rft commands, see the rft(1) man page.
The following terms are commonly used with the File Transfer Agent (FTA):
A file transfer service is a program that provides FTA with access to a network system that uses a specific file transfer protocol.
A unique FTA domain_name is assigned to each of the file transfer services that are available to FTA. A domain name is subsequently used to identify a specific transfer service.
network peer-to-peer authorization (NPPA) lets users transfer files without sending a password across the network. It requires FTA on the local system and support for network peer-to-peer authorization on the remote system. It can be used to authorize both batch and interactive file transfers.
A file transfer request is an object containing information that describes the file transfer operations to be performed by FTA on behalf of a user. Each request is a separate file, which is located in the FTA queue directory.
A queue directory is a file system directory that contains file transfer request files.
To transfer files to and from a remote host, use the following command:
ftua |
 | Note: You can use this command only on NQE nodes. |
The ftua command uses the File Transfer Agent (FTA) component of NQE to transfer files.
You might choose to use FTA for the following reasons:
You can queue your transfers. You can execute file transfers immediately or queue them for later execution. If the transfer is queued, it is executed after you leave the utility, letting you proceed to other tasks.
You can display queued transfers. If you have issued a file transfer request in queue mode, you can display details about the request. To view the status of an FTA transfer, you can use either the NQE GUI or the qls command.
Your transfers are retried. If your file transfer fails for some transient reason (such as a network link failing), FTA automatically requeues the transfer. Retries are useful in batch requests because your requests will not abort if a transfer cannot occur when it is first tried.
You do not have to provide passwords. FTA provides network peer-to-peer authorization (NPPA). NPPA lets you transfer files without specifying passwords in either batch request files or in .netrc files or by transmitting passwords over the network. For more information on NPPA, see “Using NPPA”.
It provides both synchronous and asynchronous reliable file transfer. If a transient error condition occurs during the transfer, transfers are retried. Retries are useful when transferring files from within an NQS request.
To start the ftua utility, type ftua and press RETURN. The ftua prompt (ftua>) appears.
$ ftua ftua> |
At this point, you can execute any ftua commands that do not require a connection to a remote host. Examples are domain, open, and help.
The ftua utility lets you connect to any transfer service that is configured by your administrator. To select the file transfer service to which you want to connect, use the following command:
ftua> domain domain_name |
The default value of domain_name is inet.
If you are transferring files to or from another NQE system, use nqe as the domain_name.
If you are transferring files to or from a non-NQE system, use ftp as the domain_name.
To connect to a remote host, use the following command:
ftua> open hostname |
The following example shows a connection sequence to a host with verbose mode on. Verbose mode displays all ftua messages. The domain name is nqe. The remote host is ice, and the user ID is you.
ftua> verbose Verbose mode on. ftua> domain nqe 250 SITE command successful. ftua> open host5 250 SITE command successful. Name (ice:you): Password: 250 PASS command successful. ftua> |
You can include your user name and password for the remote host in the .netrc file on the system from which you issue the ftua command, as described in “Using Autologin”. If you do, you are not prompted for a user name or password.
If you are using NPPA, you can press RETURN at the password prompt. For a description of NPPA, see “Using NPPA”.
A shortcut for establishing an ftua connection is to type ftua, a host name, and a domain name after the operating system prompt, as shown in the following example:
$ ftua ice nqe Name (ice:you): Password: ftua> |
FTA inserts your user name on the local host. If you have the same user name on the remote host, you can press RETURN and type in your password.
A connection with the remote host is established immediately, and you can execute any ftua command.
The ftua utility can execute file transfers in one of two modes:
immediate mode transfers the file immediately after you type a command. You cannot type any more ftua commands until the file transfer completes. A message informs you of the success or failure of the transfer. If the file transfer fails, you must reenter the command.
queue mode queues the request to await execution. The queue contains requests from all ftua users. The request is not executed until you exit ftua. If you enter the wait command, the transfer is completed first, and then the session is ended. Queue mode is normally used when you do not want to wait for a transfer to complete before continuing, but you want to be sure the transfer will complete successfully. Using queue mode, if the communications link fails in the middle of the transfer, FTA will requeue the transfer automatically.
If the file transfer fails with a transient error, the request remains in the queue and can be recovered as described in “Failure Notification”.
In queue mode, by default, you are sent a mail message for each request that fails. You can request that a mail message be sent to you to report either the success or the failure of the file transfer request by using the following command:
ftua> notify
When you first enter ftua, you are in immediate mode, unless you use the -q command line option to change to queue mode, as follows:
ftua -q ice nqe |
After you enter ftua, you also can type queue and press RETURN to enter queue mode. To return to immediate mode, type immediate and press RETURN. To determine your current mode, look at the last line of the display produced by the status command, as shown in the following example:
ftua> queue ftua> status Connected to sun20. No proxy connection. Mode: stream; Type: ascii; Form: non-print; Structure: file Verbose: off; Bell: off; Prompting: on; Globbing: on Store unique: off; Receive unique: off Case: off; CR stripping: on Ntrans: off Nmap: off Hash mark printing: off; Use of PORT cmds: on Queue mode: on ftua> |
You can specify the type of file you want to transfer by using the following command:
ftua> filetype |
The type of files supported varies, depending on the domain_name you use and the underlying file transfer protocol selected. The following filetypes are available:
ascii (file contains ASCII, or character, data; the line boundary structure of the file is preserved)
binary (file contains binary data; no interpretation is made of the data within the file, and the remote system stores the file so that the file can be retrieved unchanged)
ebcdic (rft does not support this file type)
image (has the same effect as binary file transfers; rft does not support this file type)
tenex (sets type to local byte size and has the same effect as binary file transfers; rft does not support this file type)
For additional information about file types supported, see the ftua(1) and rft(1) man pages.
To copy a file from a remote host to your current directory on the local system, use the following command:
get remote_file local_file |
File names can be full path names or relative to the working directory.
The following example shows the messages displayed if you are in immediate mode with verbose mode on. If verbose mode is off, messages are not displayed after the get command line.
ftua> get file1 file2 200 FILE command successful. 220 Command completed. |
If you omit local_file, ftua uses remote_file to name the file on the local system.
To copy a file from the local system to your home directory on a remote host, use the following command:
put local_file remote_file |
File names can be full path names or relative to the working directory. The following example shows the messages displayed if you are in immediate mode with verbose mode on:
ftua> put file1 file2 200 FILE command successful. 220 Command completed. |
If you omit remote_file, ftua uses local_file to name the file on the remote system.
To copy multiple files to a remote host, use the following command:
mput filenames |
The filenames argument is a list of local file names; you can also designate multiple file names by using file name globbing (that is by using wildcard characters) to copy all files at one time. (Globbing is on by default. For summary information on globbing, see the ftua(1) man page.) File names can be full path names or relative to the working directory.
| Note: The ftua utility has no equivalent command to copy multiple files from a remote host to your directory on the local system. |
Interactive prompting is on by default. If interactive prompting is on, you are asked to verify whether you want each file to be transferred. The following command opens a connection to host ice using domain nqe and turns off interactive prompting for multiple file transfers:
ftua -i ice nqe |
You can toggle prompting on or off. To see the current setting for prompting, use the status command. To change the setting, use the prompt command, as shown in the following example:
ftua> prompt Interactive mode off. ftua> prompt Interactive mode on. ftua> |
The following example shows the transfer occurring with interactive prompting enabled and verbose mode off. The interactive prompt lets you cancel the transfer of one or more of the files designated on the command line.
ftua> mput file1 file2 file3 mput file1? y mput file2? n mput file3? y |
The ftua block mode is primarily used to transfer Cray Research binary-blocked files between UNICOS and IBM's Multiple Virtual Storage Operating System (MVS) FTP. To perform successful get and put operations, the remote FTP server must support the FTP block transfer mode. (For text file transfers, use the default FTP ASCII mode transfer.)
Records must be disassembled or assembled into FTP blocks to facilitate transfer. When executing a block mode put of a file, the ftua client uses the Cray Research flexible file input/output system (FFIO) to read each record from the UNICOS file. The record is sent to the remote FTP server using as many FTP blocks as necessary to complete the transfer; these FTP blocks are reassembled into a record on the remote side. When executing a block mode get, FTP blocks are read and stored until end-of-record is encountered; these FTP blocks are written to a file as one record using FFIO. In either case, the remote FTP server must perform complementary actions, assembling or disassembling records into or from FTP blocks.
Currently, the only FTP server known to support block transfer mode in this manner is that provided by IBM's TCP/IP for MVS. Refer to the manuals supplied with this product for more information on using IBM's FTP server. The remainder of this section assumes that this is the FTP server you are using.
To use block mode file transfers successfully, you must have knowledge about the size of the data records to be transferred, the file structure on UNICOS, and the dataset structure on MVS. Use sets of ftua commands to inform the FTP client (ftua) and the MVS FTP server about the necessary file attributes and record size, as follows:
For the UNICOS file, use a qualifier in the local file specification on the put or the get command to specify the FFIO attributes. (FFIO attributes are described in the Application Programmer's I/O Guide, publication SG-2168.)
For the MVS dataset, use the ftua site command to send information to the server about the dataset characteristics. (A subset of these parameters is similar, but not identical, to a subset of the parameters on the MVS DD JCL command.)
Note: To see the parameters accepted by the site command for the remote server, enter the following: ftua> rhelp site
You can use the verbose command to see warning messages sent by the remote server that may help to diagnose problems with site command parameters.Use the ftua blkmdsize command to specify the maximum-size FTP block to be used by ftua when sending a file in block mode.
To receive a dataset from MVS to a UNICOS file within an ftua session, take the following steps:
Use the ibmblock command to set mode to block and type to ebcdic. Typically, you do not need to specify a site command if you want the server to read the dataset using the attributes stored in the MVS catalog.
On the get command, append the FFIO attributes in parenthesis to the local file specification to describe how the file should be written on UNICOS. ftua uses FFIO to write a file whenever mode is block. If no FFIO attribute is specified, the file is written in UNICOS binary blocked format. (FFIO cos format as shown in the specific example.) The get command syntax follows:
get remote_file local_file (ffio_attributes)
A specific example of the get command follows:
ftua> get mvsqual.dsn crayfile(cos) |
To send a UNICOS file to an MVS dataset within an ftua session, take the following steps:
Use the ibmblock command to set mode to block and type to ebcdic.
When creating a new MVS dataset, use the site command to specify its characteristics.
Depending on the maximum record size of the UNICOS file, and the blocksize and record format of the MVS dataset, you may need to use the blkmdbsize command to specify the maximum size of each FTP block that ftua will send to the server. The default FTP block size used by ftua is 16384 bytes.
blkmdbsize size_in_bytes
On the put command, you must append the FFIO attributes in parenthesis to the local file specification to describe how the UNICOS file should be read. ftua uses FFIO to read a file whenever mode is block. If no FFIO attribute is specified, the file is assumed to be in UNICOS binary blocked format (FFIO cos format). The put command syntax follows:
ftua> put local_file (ffio_attributes) remote_file
A specific example of the command follows:
ftua> put crayfile(cos) mvsqual.dsn |
 | Caution: Be careful when specifying UNICOS FFIO and MVS dataset attributes. In many cases, if you accept the default values or specify values inconsistent with the structure of the UNICOS file or MVS dataset, the file transfer may complete without error, but the records in the dataset may be truncated or otherwise incorrect. |
The default dataset characteristics for datasets created by the FTP server can be customized by the MVS system administrator. Depending on your application, you may want to explicitly specify key site parameters to minimize the reliance on particular site defaults.
| Caution: Use only one site command per session. Unexpected side-effects may occur as a result of new default values overriding values specified on previous site commands. Also, many site command parameters apply only to datasets created by FTP; if the dataset already exists, existing characteristics may be used without warning. |
You can use the server stat command to get a listing of the current status of many of the server's current transfer settings.
ftua> rquote stat |
Avoid the use of recfm=v or recfm=vbs because you may receive results that are not valid without warning.
For files with arbitrary-sized records or records larger than 32768 bytes, use datasets with characteristics recfm=vbs and lrecl=x. Use the blkmdbsize command to set the FTP transfer size to be 8 bytes less than the MVS blocksize. For example:
ftua> ibmblock ftua> blkmdbsize 32752 ftua> site recfm=vbs lrecl=x blocksize=32768 ftua> put crayfile(cos) mvsqual.dsn |
Some choices for blkmdbsize and blocksize versus record size may lead to inefficient storage of the MVS dataset. In general, choose values such that the smaller of the average record size or the blkmdbsize is close to but less than (blocksize - 8). A complete discussion of UNICOS file formats, MVS dataset characteristics, their interaction with FTP settings, and of data storage efficiency is beyond the scope of this section.
Remember that the FFIO specification is for the UNICOS file format, not the MVS dataset. Unless the UNICOS file is already in an IBM format, do not use FFIO IBM format specifications.
To append a local file to a remote file, use the following command:
append local_file_name remote_file_name |
The file name can be a full path name or relative to the working directory.
The following example appends the contents of the local file this to the remote file that:
ftua> append this that |
To delete a file from the remote host, use the following command:
delete filename |
The file name can be a full or relative path name.
The following example deletes the remote file file1:
ftua> delete file1 |
If you have issued a file transfer request in queue mode, you can display details about the request in the following ways:
You can use the NQE GUI. For each request that has an FTA transfer associated with the request, the NQE GUI Status window's View menu Job Summary display contains a Yes in the FTA Used column.
You can view the status of an FTA transfer in the following ways:
Using the Status window, select the View menu FTA Summary option which displays a one-line summary of all transfers.
To display a detailed status of a specific transfer, place the pointer over the transfer name and double-click the left mouse button. To cancel the detailed FTA Summary display, click on the display's Cancel button by using the left mouse button.
Using the Status window's default Job Summary display, highlight the request by placing the pointer on the request line and clicking on the left mouse button. Select the Actions menu, and then select Detailed FTA Status. To cancel the Detailed FTA Summary display, click on the display's Cancel button by using the left mouse button.
You can use the qls command. To obtain a one-line list of all your file transfer requests that are currently in the queue, use the qls command, as shown in the following example. A unique queue identifier located in the QID column identifies each file transfer request:
ftua> qls --QID-- ---Queued On --- --User-- ---State--- -----Status----- aa12972 Mon Jan 5 22:05 george Active UA connected aa12977 Mon Jan 5 22:15 george Active UA connected
To display details of all requests currently in the queue, use the qdir command. To display more details about a particular request, use the qdir identifier command, as follows:
ftua> qdir aa12972 --QID-- ---Queued On --- --User-- --Group-- aa12972 Mon Jan 5 22:05 george cray State: Active Status: UA connected Priority: 0 Last Attempt: Never Controlling PID: 12972 Domain: nqe Host: sun20 Username: george Copy (put) LocalFile: /home/sun401/george/verse1 RemoteFile: verse1
To abort a file transfer when operating in immediate mode, press the terminal interrupt key (usually CONTROL-c), as in the following example:
ftua> get file1 file2 CONTROL-c |
If you used the put, mput, or append command, it is halted immediately. If you used a get command, it may take a little time before it ends, depending on the domain that you selected.
To delete a transfer in queue mode, use qdelete followed by the queue identifier for the request, as follows:
ftua> qdelete aa12977 |
To obtain the queue identifier for a request, see “Displaying Queued Transfers”.
The wait command blocks your use of ftua until FTA completes the queued request. After the request has completed, ftua exits, as in the following example:
latte% ftua -qv ice ftp Connected to localhost. 220 latte FTA server (Version 5.0 (11.1)) ready. 250 QMOD command successful. 250 DOMA command successful. 200 SITE command successful. Name (ice:jane): 331 Password required for jane. Password: 200 Login to remote fts successful. ftua> get x.x 200 FILE command successful. 220 COPY command queued (aa000LP). ftua> wait Waiting for request aa000LP... Request aa000LP completed. latte% |
The wait command does not guarantee successful file transfer. If a request fails as a result of a transient error, it is requeued but not recovered. For information on FTA recovery, see NQE Administration, publication SG-2150.
To close a connection to a host but remain in ftua, use either the close or the disconnect command, as in the following example:
ftua> close 221 Goodbye. ftua> |
To end the ftua session, use either the bye or quit command, as in the following example:
ftua> bye $ |
This section provides an example of using ftua in its immediate and queue modes. For a summary of ftua commands, see the ftua(1) man page.
First Jane wants to access a remote host called moon. She types ftua and the remote host name moon (moon is an NQE system), followed by the domain name nqe.
$ ftua moon nqe Name (moon:jane): Password: ftua>
Jane wants to transfer several files immediately, without having to queue them. She does not want to be prompted for each file, so she turns off interactive prompting.
ftua> prompt Interactive mode off. ftua>
Jane is now ready to copy the files to host moon. Because all of the file names begin with the prefix janedata, Jane uses file name globbing (that is uses wildcard characters) to copy all files at one time. (Globbing is on by default. For summary information on globbing, see the ftua(1) man page.)
ftua> mput janedata* ftua>
As you can see, no information is displayed about the actual transfers that occurred.
If Jane wants some information about the transfers, she can turn on verbose mode before executing mput:
ftua> verbose Verbose mode on. ftua> mput janedata* 200 FILE command successful. 220 Command completed. 200 FILE command successful. 220 Command completed. 200 FILE command successful. 220 Command completed. ftua>
To display even more information, Jane can set the debug feature to be on, as in the following example:
ftua> debug 1 Debugging on (debug=1). ftua> mput janedata* ---> FILE /sub/jane/janedata1 200 FILE command successful. ---> STOR janedata1 220 Command completed. ---> FILE /sub/jane/janedata2 200 FILE command successful. ---> STOR janedata2 220 Command completed. ---> FILE /sub/jane/janedata3 200 FILE command successful. ---> STOR janedata3 220 Command completed.
Jane closes the connection to host moon, as follows:
ftua> close ftua>
Jane wants to copy a file called weather.oct on her local host to host neptune. weather.oct is a large file, and Jane does not want to wait until it completes before continuing, but she does want to be sure the transfer will complete successfully.
Because the link to neptune has a reputation for being unreliable, Jane decides to execute the transfer in queue mode. That means she does not have to stay in ftua until the transfer completes. However, she can still be sure that, if the communications link fails in the middle of the transfer, FTA will requeue the transfer automatically.
Before opening the connection to neptune, Jane enters queue mode.
Because weather.oct contains binary data, Jane selects a file transfer type of binary before requesting the transfer.
ftua> queue ftua> open neptune dec Name (neptune:jane): Password: ftua> binary ftua> put weather.oct ftua>
Jane wants to examine the queue to see whether her transfer request is there. Because she cannot remember the command to use, however, she types help to get a list of command names, and then she types help followed by the command name (qdir) to ensure that she has the correct command.
ftua> help Use `help <command>' to get help on commands. Commands may be abbreviated. Commands are: ! dir mdir qdelete setdefault $ disconnect mkdir qdir site account domain mls qls status append form mode queue struct ascii get moveout quit trace bell glob mput quote type binary help nlist recv user blkmdbsize ibmblock nmap rename umask bye immediate notify reset verbose cd image ntrans rmdir wait cdup lcd open rhelp ? close lhelp prompt rquote delete ls put runique debug macdef pwd send ftua> help qdir qdir list contents of file transfer queue (long) ftua>
To see details about queue entries, Jane types the qdir command:
ftua> qdir --QID-- ---Queued On --- --User-- --Group-- aa15872 Tue Jan 6 17:25 jane cray State: Active Status: UA connected Priority: 0 Last Attempt: Never Controlling PID: 15872 Domain: nqe Host: neptune Username: jane Copy (put) LocalFile: /sub/jane/weather.oct RemoteFile: weather.oct ftua>Because Jane wants to receive mail when the file transfer request succeeds, she types the following command before ending the ftua session:
ftua> notify success on ftua>
When Jane ends the ftua session, the queued file transfer is processed. Jane uses the following command to end the ftua session; any active ftua connections are also closed by using this command:
ftua> bye $
The macdef command lets you define macros within ftua. A macro definition is in effect only for the current ftua session. To save macro definitions, put them into the .netrc file. For more information on the .netrc file format, see “Creating .netrc File Entries”.
The following example illustrates the use of the macdef command to define a macro called newdir. The macro newdir creates a new directory at the remote machine by using a path name (/sub/jane/test) supplied as the first argument on the macro command line. It then changes the current directory to be the newly created one and displays the current directory.
Within the macro definition, a $ followed by a numeral (or numerals) is replaced by the corresponding argument on the command line when the macro is invoked. For example, $1 is replaced with the first command line argument.
An empty line terminates the macro input mode.
$ ftua chemistry nqe Name (chemistry:jane): Password: ftua> macdef newdir Enter macro line by line, terminating it with a null line mkdir $1 cd $1 pwd ftua> $ newdir /sub/jane/test 220 "/sub/jane/test" is current directory. ftua> |
Macros remain defined until you execute a close, bye, or quit command.
To initiate a file transfer from within a request file, you can use here document syntax, as in the following example:
ftua -in machine nqe << EOF fred_bloggs password get remote_file quit EOF |
The << signals the construction of the here document. The word that follows (EOF in this case) is the string used to delimit the input, meaning that the next occurrence of the string on a line by itself is the end of the here document.
To initiate file transfers, you can use either ftua or rft, with or without the use of passwords.
To use ftua or rft in nopassword mode, both machines must have network peer-to-peer authorization (NPPA) enabled as described in “Using NPPA”.
You can use the following syntax in the request file to transfer files to and from a machine called aardvark that has the domain nqe. Both of the following examples use NPPA for user authentication. If NPPA is not used, ftua or rft requires a password.
The following example shows ftua used in a batch request:
ftua -in aardvark nqe << EOD
smith #<--- username
#<--- blank line for NPPA
get file1 #<--- ftua request
binary #<--- ftua request
get file2 #<--- ftua request
put file #<--- ftua request
quit #<--- exit ftua
EOD |
The following example shows rft used in a batch request (for an explanation of using the rft command, see “Using rft”):
rft -function get that_file1 new_file -user smith \ -host aardvark -domain nqe -type binary -nopassword |
When the UNICOS multilevel security (MLS) feature or the UNICOS/mk security enhancements are running on your system, use the ftua command to transfer classified files from a UNICOS MLS or UNICOS/mk security-enhanced system to a remote node. If you use ftua on the remote node, you can transfer only files at the active security label assigned to you at login. There is no mechanism for changing your security label within ftua.
When you have logged into your UNICOS MLS or UNICOS/mk security-enhanced system, set your active security label to that of the file you wish to transfer, then execute the ftua command. You must be in a directory that can accommodate a file created at your active security label. If the remote node supports your security label you can transfer the file. Files that are transferred to the UNICOS MLS or UNICOS/mk security-enhanced system are labeled with your active security label at the time of file creation. The examples that follow illustrate common transfer procedures under MLS and their results.
In example 1, Jill wants to transfer the file called testdata from cray to snoopy. testdata has a security level of 1 and the test compartment. Jill adjusts her security level and compartment settings to match the file's security level and compartment. She then executes the ftua command, but is denied access because the network access list (NAL) entry for snoopy does not support this level or compartment.
cray$ spget -f testdata Security Values for: testdata level: 1 level1 compartments: 010 test class: 0 class0 categories: 0 none flags: 0 none cray$ setulvl 1 setulvl: New security label is Level[1:level1] Compartments[none] cray$ setucmp test setucmp: New security label is Level[1:level1] Compartments[test] cray$ ftua snoopy ftua: connect: Permission denied ftua> quit |
In example 2, Jill tries to transfer the file to friend. The transfer is successful because the NAL entry for friend supports her security label.
cray$ ftua friend Connected to friend 220 friend ftua server (Version 4.15 Fri Mar 6 14:20:46 PST 1998) ready. Name (friend:jill): 331 Password required for jill. Password: 230 User jill logged in. ftua> put testdata 200 PORT command okay. 150 Opening data connection for testdata (234.6.12.4,1035). 226 Transfer complete. ftua> quit |
In example 3, Jill tries to transfer a file to cray from friend. First, she changes to a directory where she can create a file with a security level of 1 and the test compartment. The transfer is successful because the NAL entry for friend supports her security label, and the file can be created in her current directory.
cray$ cd level1/test cray$ ftua friend Connected to friend 220 friend ftua server (Version 4.15 Fri Mar 6 14:20:46 PST 1998) ready. Name (friend:jill): jill 331 Password required for jill. Password: 230 User jill logged in. ftua> get friend.file 200 PORT command okay. 150 ASCII data connection for friend.file (128.162.82.15,1187 226 ASCII Transfer complete. ftua> quit 211 Goodbye. $ spget -f friend.file Security Values for: friend.file level: 1 level1 compartments: 10 test class: 0 class0 categories: 0 none flags: 0 none |
Files specified as arguments to ftua commands are processed according to the following rules:
If you use wildcard characters (that is, if globbing is enabled), local file names are expanded according to the rules used in the C shell, csh(1).
If get commands do not specify a local file name, ftua uses the remote file name. To alter this, use an ntrans or nmap setting.
If you do not specify a remote file name for mput and put commands, ftua uses the local file names. To alter this, use an ntrans or nmap setting.
If you specify the file name -, the standard input (for reading) or standard output (for writing) is used. This file naming option is not available to Action commands, which are listed in the ftua(1) man page.
For summary information on globbing, ntrans and nmap, and a listing of the Action commands, see the ftua(1) man page.
Transfer requests you make in queue mode are processed after you exit ftua. During the processing of a request, one of the following might occur:
The request completes successfully.
A failure occurs that prevents the request from being started. In such cases, the request is removed from the queue.
A failure also could occur during the execution of the request. For example, the request could involve getting two files from the remote system, but one of the files does not exist. If possible, all valid actions in a request are completed, but some failures could mean that the request cannot be processed any further, and so it is removed from the queue.
A transient error occurs. A transient error is a temporary error that prevents the request from being processed at the current time. For example, the remote system involved in the request could be down, but it might become available later.
If a transient error occurs, the request remains in the queue and can be retried. Generally, the NQE administrator sets up an automatic recovery process that retries such requests at regular intervals. It is possible for you to recover your own files; for further information, see NQE Administration, publication SG-2150.
To request that a mail message be sent to you when a request completes successfully or when a failure occurs, use the following command:
ftua> notify |
By default, a mail message is sent only if a failure occurs. For failures, the mail message includes a description of the failure that has occurred, as follows:
To: fred
From: MAILER-DAEMON (File Transfer Agent)
Subject: File transfer aa17087 (failed)
Status: R
File transfer request aa17087 has failed.
Diagnostic message follows:
Login incorrect.
Request description and status follows:
--QID-- ---Queued On --- --User-- --Group--
aa17087 Mon Mar 23 09:44 fred craygrp
State: Active
Status: Connected
Priority: 0
Last Attempt: Mon Mar 23 09:44:48
Controlling PID: 17091
Domain: nqe
Host: cray1
Username: fred
Copy (get)
RemoteFile: .login
LocalFile: /x/fred/.login |
To determine whether a transient error has occurred, use the qls or qdir command. The following screen shows how an example of the display produced by qls indicates transient errors:
ftua> qls --QID-- ---Queued On --- --User-- --State-- ----Status---- aa02497 Fri Mar 20 16:19 chris Queued Network connection timeout aa02523 Fri Mar 20 16:29 chris Queued Network connection failure |
The rft(1) command uses one command line to copy files between the local host and another host. You can use this command on NQE nodes only.
The rft command has the following advantages over other file transfer commands:
It is a one-line interface to FTA. This makes it easier to use in batch job requests.
It provides both synchronous and asynchronous reliable file transfer. If a transient error condition occurs during the transfer, transfers are retried. Retries are useful when transferring files from within an NQS request.
If you disable the synchronous feature by selecting the -nowait option, the transfers are done in asynchronous fashion but are still reliable.
rft provides an option that deletes the local file on the completion of a transfer. This is useful when transferring files at the end of an NQS request to the system from which you submitted the request.
For a detailed description of the command, see the rft(1) man page.
In its simplest form, rft can copy a file from a remote system to a file on the local system. The following example transfers remfile on host2 to locfile on the local host:
rft -user jake -password Zapx -host host2 -function get \ remfile locfile |
You can abbreviate the options, such as -user, if the abbreviation is not ambiguous. For instance, you cannot abbreviate -host as -h, because it might be confused with the -help option. You can, however, abbreviate -host as -ho.
| Note: When you use rft within a script or batch request file, do not abbreviate the options. New options might be implemented that begin with the same sequence as an abbreviated option and thus introduce an ambiguity. |
If you are logged on interactively, rft will prompt for a password only for the remote host. To suppress the prompt, specify the password on the command line by using the -password option. If you do not have to specify a password, use the -nopassword option.
To reverse the direction of the file transfer, change the function from get to put. The source file name is always listed first and the destination file name second, whichever direction the transfer is going. The following command copies locfile from the local system to remfile on host2:
rft -user jake -password ZapX -host host2 -function put \ locfile remfile |
The autologin feature lets you authenticate yourself on a remote system by using a user ID and password that are stored in the .netrc file. The .netrc file supports autologin for ftua commands. You cannot use the autologin feature, however, if you have the UNICOS multilevel security (MLS) feature or the UNICOS/mk security enhancements enabled.
The .netrc file is an authorization file that contains host and user information that the remote system verifies before the file transfer session begins. ftp also uses the .netrc file.
To use autologin, create the .netrc file in your home directory. If FTA finds this file, it uses the information to log you in to the remote host automatically. If you do not have an .netrc file, the system prompts you for your login name and password.
The .netrc file is a simple text file. To create or modify it, you can use any standard text editor, such as vi(1).
Although autologin is very convenient, it does present a major security threat to the system. If .netrc contains password or account information, FTA requires that the file permissions are set so that the owner of the file has exclusive read and write permissions. Set the file permissions by using the chmod 600 .netrc command. If the file permissions allow any other user to read and write the file, your transfer will fail.
The .netrc file can contain one or more entries. Each entry describes default values and macros to use when connecting to a specified remote host. Each entry is on a separate line. Each entry is composed of token pairs that include a keyword and a value.
The recognized keywords are machine, login, password, account, and macdef.
To separate token pairs, use any of the following characters:
Space
Tab
Newline
String of characters between two double quotation marks
To embed any of these special delimiter characters into a token pair, precede it with a \ symbol.
The machine remote_hostname token pair defines the start of an entry.
All other token pairs are optional. You can specify them in any order, though they usually are given in the order that follows. If you omit necessary information from your .netrc file, FTA prompts you for it.
| Note: The macdef macro_name token pair is different from the others. After the macdef macro_name token pair, all characters up to a blank line are assumed to be the definitions of a macro. |
The following is a list of the permissible token pairs:
| Token pair | |
Description | |
| machine remote_hostname | |
Identifies the name of the remote host to which a connection will be established. When you start ftua, the .netrc file is searched for a machine keyword that matches the remote host name you specify. After a match is found, the subsequent .netrc token pairs are processed until the end of the file is reached or until another machine keyword is found. | |
| login login_name | |
Specifies the name of a user at the remote host. If the login keyword is present, the autologin process uses login_name to log in to the remote host. | |
| password password | |
Specifies a password for login_name. If the password keyword is present and the .netrc file can be read by anyone but the user running ftua, the autologin process aborts. | |
| account account_name | |
Supplies an additional account password if required. | |
| macdef macro_name macro | |
Defines a macro for the ftua session. A macro is defined with the specified name. The macro's contents begin with the next .netrc line and continue until a blank line is encountered. If a macro called init is defined, it is executed automatically as the last step of the autologin process. | |
The following example .netrc file contains entries for three different remote hosts. The line machine biology login bonnie indicates that, when connecting to host biology, you must use the login name bonnie. Because the password is omitted, you are prompted for the password during each login process.
The line machine chemistry login alice indicates that, when connecting to host chemistry, you must use the login name alice, and it also defines two macros, lsf and pwdlsf.
The line machine blackhole login anonymous password bonnie is an entry for anonymous ftua. The anonymous facility lets you use ftua to access another host without having an account or password on that host. The login name for anonymous ftua is usually anonymous. The password should be a name that describes the user. This example uses the login name anonymous and the password bonnie. Usually, the anonymous facility is not enabled. When it is enabled, only a limited number of files can be accessed on that host.
# .netrc file example
machine biology login bonnie
machine chemistry login alice
macdef lsf
ls -CF
macdef pwdlsf
pwd
ls -CF
machine blackhole login anonymous password bonnie |
network peer-to-peer authorization (NPPA) lets you log on to a remote host without sending a password across the network in a request script file, a .netrc file, or from the command line. NPPA requires the use of FTA on the local system and support for the NPPA process on the remote system. You can use it to authorize both batch and interactive file transfers.
You must enter the name of your NPPA domain on the ftua command line. Ask your NQE administrator for the name.
The following lines in a batch request file transfer a file named nqeuser.data:
1) #QSUB -x 2) ftua -n hot1 nqe << EOF 3) user nqeuser 4) 5) get nqeuser.data nqeuser.data 6) bye 7) EOF |
| Line | Description |
| 1 | Specifies that NQS environment variables are exported. |
| 2 | Specifies the name of the host (hot1) on which your file is located and the NPPA domain (nqe). The characters << begins the here document that accepts input until the termination string (EOF) is encountered. The -n option specifies that you want to use NPPA. |
| 3 | Logs you in. |
| 4 | Is blank because it sends the RETURN that you would press at the password prompt if you were using ftua and NPPA interactively. |
| 5 | Transfers the nqeuser.data file from hot1 to the execution server. |
| 6 | Logs you out of ftua. |
| 7 | Signals the end of the ftua commands in the batch request file. |