HSIRC File

The hsirc files contains settings that are read during HSI initialization.  The HPSS administrator may optionally create a global hsirc file that is read by all HSI clients on a machine, and users may optionally create a private file in $HOME/.hsirc.


In general, settings that are in the user's private .hsirc file override settings that in the global hsirc file.  The only exception to this is the "hpssconf_path" setting, which is only recognized in the host-global hsirc file.


HSIRC File Structure


The hsirc file consists of comment lines, global declarations, and site stanza declarations.


Comment lines are lines that are empty or that begin with a sharp sign "#" as

the first non-whitespace character of the line. 


Parameter Line Format


In general, parameter lines are of the form

        key = value

Whitespace preceding and following the "=" is optional.


Global Parameters

Global parameters are contained in the "global" stanza, which begins with the reserved stanza name "global:" as follows:

global:

   global declarations


Parameters that can be contained in the global stanza are listed in table 1, below.


Site-Stanza Parameters

Site stanzas begin with a line containing a stanza name, which is recognized by the presence of single token on a line which is terminated by a colon ":" character. The reserved stanza name "global" contains settings that apply to all connections, such as the prompt string.  


site_stanza1:   <--- stanza name "site_stanza1"

   stanza declarations

site_stanza2:

   stanza declarations

...


Site stanzas contain settings that apply only to connections to that stanza.  Parameters that can be contained in site stanzas are listed in table 2, below.


Parameter Ordering and Restrictions


In general, parameters in either the global or site-stanzas can be specified in any order.

However, the following restrictions apply in site-stanzas:


1. Any authentication mechanism which is supported must be specified via an authmethod = method line,  and any parameters that are sub-items of the authentication method must follow the line, and precede any other authmethod line.


For example, to specify that “combo” and “kerberos authentication” methods are available, and that:

a.  the kerberos credentials cache file to be used is "/users/joline/.creds_prod"

and

b. the keytab file to be used is at "/users/joline/.private/.ktb_creds", the following could be specified:


# combo authmethod is available at this site

authmethod = combo


# kerberos  authmethod is available at this site

authmethod = kerberos

credfile = /users/joline/.creds_prod

keytab = /users/joline/.private/.ktb_creds



Rules for duplicated stanza names and duplicated stanza declaration:


- If stanza names are duplicated, then the contents are merged.  If the same parameter is specified in more than one of the duplicate stanzas, in general, the last entry found is used.  Also, if the user's private .hsirc file contains a stanza whose name is a duplicate of a stanza in the global hsirc, the user entries override the global settings.


Site stanzas are invoked in one of following ways:

- by specifying the "-s sitename" HSI command line parameter

- by specifying the "site = sitename" setting in the global stanza

- by specifying the "-s sitename" option on the connect command


Table 1: HSIRC Global Stanza Settings

Option

Valid In

Notes

autobackup = on | off

all hsirc files

specifies whether automatic backup of existing files should occur for get or put commands

authmethod = authtype [:authtype …]

all hsirc files

specifies one or more colon-separated authentication methods to be tried. Authmethods are tried in succession from left to right until authentication succeeds or all methods have been tried.
Valid methods are:

  • combo
  • dce (deprecated - same as "combo"
  • gsi
  • ident
  • keytab
  • kerberos
  • local
  • pam [HSI 5.0.1+]

autoschedule = on | off

all hsirc files

enables or disables optimization of tape mounts for get, stage

cksum_enabled = on | off

all hsirc files

Specifies whether hash checksums should be enabled for all "get" and "put" operations from/to HPSS.
Note: Checksums are stored in HPSS metadata.
The default for this option is defined by the HSI Admin when HSI is compiled - normally "off". When this option is enabled, HSI will issue warning messages on "get"s if the HPSS file does not contain a checksum. The "-c" option can be specified on get/put commands to enable or disable checksum generation/verification

cksum_type = type

all hsirc files

Specifies the checksum hash type to be used when generating checksums in HPSS. Legal values are:

  • none
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
  • md5 (Default)
  • crc32
  • adler32

columns = value>

all hsirc files

sets number of columns per line (display page width)

copies = n>

all hsirc files

sets the default number of file copies to request when creating or copying files in HPSS

drive = letter

all hsirc files

sets the logical drive letter to associate with the current connection. letter must be in the range [A-Z] or [a-z].

dcreate_mode = octal creation mode

all hsirc files

Specifies the creation mode bits to use when creating a new directory, e.g.
dcreate = 0755

enable_san3p = on | off

all hsirc files

Enables or disables the use of SAN3P I/O for HPSS file transfers. The default is off. SAN3P I/O is only supported on Linux platforms.

enable_lfm_io = on | off

all hsirc files

[future]Enables or disables the use of Local File I/O for HPSS file transfers. This feature requires that HPSS mover(s) be able to read/write the local filesystem(s).

enable_sharedmem = on | off

all hsirc files

Enables or disables the use of shared memory for HPSS file transfers. The default is off. Shared memory will only be used if both the HSI client and the HPSS mover live on the same machine

enable_ta_io = on | off

all hsirc files

Enables or disables the use of Transfer Agent I/O for HPSS file transfers. The default is off. Note that enabling Transfer Agent I/O requires installation of the Transfer Agent package.

family_id = id

all hsirc files

Sets the default file family ID to use for new HPSS file creates.

fcreate_mode = octal value

all hsirc files

Sets the octal file creation mode bits to be used for new file creates, for example:
fcreate_mode = 0664

firewall = on | off

all hsirc files

Enables or disables firewall mode for all connections. The "firewall" command may also be used to change the current setting for a specific connection

hpssconf_path = path

Global HSIRC file

[future]Sets the directory path for the HPSS.conf configuration file. The default path for the HPSS.conf and global hsirc file(s) is set in the HPSS_CFG_FILE_PATH environment variable

keytab = path

all hsirc files

Specifies the pathname for the Unix or KRB5 keytab file to use if keytab authentication is to be used. Metacharacters can be used in this path, for example, "%H" refers to the user's local home directory.

lines = n

all hsirc files

Sets the integer number of lines per page for terminal output. This option was used for a previous curses-based help package, but is currently unused.

max_readdir= n

all hsirc files

Specifies the integer number of entries that HSI should read from the HPSS Nameserver when doing directory scans. This option is intended for debugging.

max_smallfile_size = size

all hsirc files

Specifies the max size of files that HSI should try to transfer inline, by including the file contents in the initial get/put protocol message(s) to/from the gateway.
Note; this option is currently implemented only for the non-HPSS HSI gateway.

max_readdir = n

all hsirc files

Specifies the integer number of entries that HSI should read from the HPSS Nameserver when doing directory scans. This option is intended for debugging.

max_xfer_threads = n

all hsirc files

Specifies the maximum number of concurrent transfers that HSI should start for "get" and "put" commands. This setting can reduce, but not increase, the maximum number of concurrent transfers that is specified by the HSI administrator on the gateway server. The setting is intended for use on systems that might not have resources available to make use of the server-side max transfer setting, to allow the user to reduce the max number of concurrent transfers. The "-X" option can also be specified on "get" or "put" commands to specify the max concurrent transfers.

nologin_path = path

all hsirc files

Specifies the pathname to a "sleeper" file - if the file exists, HSI will sleep until the file is removed. This is intended for sysadmins, to provide a way to quiesce HSI connections during system maintenance periods.

promptlen = n

all hsirc files

Specifies the integer number of characters in the HSI prompt string. Must be > promptdirlen.

promptdirlen = n

all hsirc files

Specifies the maximum number of characters in the prompt string to use for expanding the directory path for %W or %w metacharacters

PS1 = prompt_string

all hsirc files

Sets the prompt string to use for interactive sessions. See the "prompt" description for details. The default is "? ".

PS2 = prompt_string

all hsirc files

Sets the prompt string to use for continuation lines for interactive sessions. The default is "> "

principal = name

all hsirc files

Sets the HPSS principal name. The metacharacter string "%U" can be used to represent the local login name on the client machine.

pwfile = filename

all hsirc files

Deprecated
Specifies the name of a local file that contains the user's plaintext password. Use of this option poses a security risk and it should only be used at sites where other security factors mitigate this risk.

site = stanza name

all hsirc files

specifies the stanza name to use for the initial HSI connection.

thread_ssize = value

all hsirc files

Specifies default thread stack size to set when launching I/O threads. value is specified as an integer value, optionally following by a suffix string (KB, MB,…). It must be >= 256KB (262144); the default value is 1MB (1048576). Setting this value too large can cause failures due to insufficient memory.

umask = octal value

all hsirc files

Specifies default umask to use at startup. If not specified in the global hsirc or the private $HOME/.hsirc file, the umask specified by the HSI Admin on the server is used if specified, or as a final fallback, the current umask in effect on the client host at the time that HSI is started is used.



OptionValid In

Table 2: HSIRC Site Stanza Settings

Option

Valid In

Notes

authmethod = method

all hsirc files

Specifies that the specified authentication method is available for this site.

Each possible authentication method that is valid for the site must be specified within the site stanza, and must immediately precede any of the options that pertain to that authentication method.

For example, to specify that “combo” and “kerberos authentication” methods are available, and that the kerberos credentials cache file to be used is /users/joline/.creds_prod , the following could be specified:

authmethod = combo

authmethod = kerberos

credfile = /users/joline/.creds_prod

cksum_enabled = on | off

all hsirc files

Specifies whether hash checksums should be enabled for all "get" and "put" operations from/to HPSS for this site.
Note: Checksums are stored in HPSS metadata.
The default for this option is defined by the HSI Admin when HSI is compiled - normally "off". When this option is enabled, HSI will issue warning messages on "get"s if the HPSS file does not contain a checksum. The "-c" option can be specified on get/put commands to enable or disable checksum generation/verification

cksum_type = type

all hsirc files

Specifies the checksum hash type to be used when generating checksums in HPSS for this site. Legal values are:

  • none
  • sha1
  • sha224
  • sha256
  • sha384
  • sha512
  • md5 (Default)
  • crc32
  • adler32

credfile = path

all hsirc files

specifies the pathname of the kerberos credentials cache file to be used when connecting to this site. If this option is not specified, the default is used, normally /tmp/krbcc_user. Use of this option is recommended when connecting to more than one HPSS site, to avoid the possibility of overwriting the credentials for one connection with those of another connection.

This option pertains to kerberos authentication, and must follow an “ authmethod kerberos ” line, as described for the “ authmethod ” option.

drive = drive_letter:

all hsirc files

specifies the logical drive letter to be used for this site. The letter may be any alphabetic character in the range a-z or A-Z. Case is not significant. If no letter is specified for this connection, HSI will find an unused letter when a connection is made to this site.

family_id = id

all hsirc files

specifies the default File Family ID to be used for file creates for this connection. The ID is an integer value that is assigned by the HPSS administrator for the site. The default is 0 (no file family).

firewall = on | off

all hsirc files

automatically enables or disables firewall mode when a connection is made.

host = hostname[,hostname ]

all hsirc files

specifies a comma-separated list of hostnames and/or IP addresses to use when connecting to this site. If more than one entry is specified in the list, an entry is randomly selected.

keytab = path

all hsirc files

specifies the pathname of the kerberos or unix keytab file to be used. This option pertains to kerberos and keytab authentication methods, and must follow an “authmethod kerberos ” or “authmethod keytab ” line within the current site stanza.

port = port_number

all hsirc files

specifies the integer port number to be used when connecting to host(s) for this site

principal = principal_name[:authmethod...]

all hsirc files

specifies the login principal name to use, and optionally a colon-separated list of authentication methods to be used. Any authentication method that is specified must be one that has been defined for this site entry by a preceding authmethod line.

The principal_name may also contain meta_characters % x where x is:

U - is replaced by the current login name

For example, at one site, the HPSS principal name is of the form “ login_name /hpss ”, and the hsirc site stanza setting is:

principal = %U/hpss

site_authmethod = method

all hsirc files

specifies the default authentication method to be used for this site stanza. This option can be specified anywhere within the site stanza, but the method must be defined on an “ authmethod ” line within the stanza. For example, the following will cause an error to be generated:

test:

site_authmethod = combo

authmethod = kerberos

authmethod = gsi

principal = %U

The error can be corrected by adding the line:

authmethod = combo

anywhere in the stanza.


site_id = id

all hsirc files

Specifies an integer site ID number. This allows the user to specify a site ID number instead of the site stanza name. Note: This option will be implemented in a future release.