###############################################################################
### Installation Instructions for gateway_submit_attributes-2.0
###############################################################################
Prerequisites:
Packages:
sudo
xsede-ca-certificates
These Perl modules:
LWP::UserAgent
HTTP::Request
JSON
Date::Manip
Net::SSL
LWP::Protocol::https
* Sys::Syslog
* Tie::File
* Getopt::Long
* Pod::Usage
* Fcntl
* FindBin
* => Likely included with your native OS Perl distribution by default.
We recommend you install these prerequisites, if available, into your OS Perl using
your native package manager. For example, on CentOS 7:
$ yum install perl-LWP-Protocol-https perl-JSON perl-Sys-Syslog perl-Date-Manip
Install using a non-privileged account. Some sites use the "software" account by
convention. The only step that requires privilege is editing /etc/sudoers.
0) Obtain an API key.
An API key needs to be generated and configured in gateway_submit_attributes.
A hash of that API key also needs to be configured into the API that
gateway_submit_attributes will call. Instructions for generating the API
key and hash and for getting the hash configured in the API are at
https://xsede-xdcdb-api.xsede.org/.
1) Create a unique user and group to run the gateway_submit_attributes script. We
recommend "gwsubmit" and will refer to this user and group as "gwsubmit:gwsubmit".
2) Create a file to act as the spool file for submissions. This file can be on
local disk or NFS. The script implments advisory locks via fcntl, so as long
as the filesystem supports them, it'll work. We will refer to this file as
/var/spool/gateway_submit_attributes.spool. The file must be readable and
writable (mode 0600) only by gwsubmit:gwsubmit.
3) Get the latest gateway_submit_attributes package at:
https://software.xsede.org/production/gatewayUserCount/
4) Untar the package:
tar -xzvf gateway_submit_attributes-2.0.tgz
5) cd gateway_submit_attributes-2.0/
6) Copy the gateway_submit_attributes script to a location in your users' path.
(the script is designed to be installed almost anywhere)
It must be mode 0755 or 0555, owned by root:root, or something
that is NOT gwsubmit:gwsubmit.
cp -p gateway_submit_attributes /usr/local/bin
chmod 0555 /usr/local/bin/gateway_submit_attributes
chown root:root /usr/local/bin/gateway_submit_attributes
7) Copy the gateway_submit_attributes.conf.example file to one of these
locations and remove the ".example" from the name. It must be mode
0400 owned by gwsubmit:gwsubmit, or mode 0640 owned by root:gwsubmit.
cp gateway_submit_attributes.conf.example /etc/gateway_submit_attributes.conf
chown root:gwsubmit /etc/gateway_submit_attributes.conf
chmod 0640 /etc/gateway_submit_attributes.conf
-OR-
cp gateway_submit_attributes.conf.example /var/secrets/gateway_submit_attributes.conf
chown root:gwsubmit /var/secrets/gateway_submit_attributes.conf
chmod 0640 /var/secrets/gateway_submit_attributes.conf
-OR-
cp gateway_submit_attributes.conf.example /gateway_submit_attributes.conf
chown root:gwsubmit /gateway_submit_attributes.conf
chmod 0640 /gateway_submit_attributes.conf
8) Edit the gateway_submit_attributes.conf and set the resource_name, api_key,
and api_id as follows using values obtained from (0).
The resource_name and api_id needs to be configured. The api_id (along with
the api_key) are used to authenticate to the API. Both of these values should
be the same and must match the XDCDB Resource Name as listed at:
https://info.xsede.org/wh1/warehouse-views/v1/resources-xdcdb-active/
Set spool_file to the file described in (2). e.g.
/var/spool/gateway_submit_attributes.spool
Do not touch rest_url_base unless instructed to change it.
Example gateway_submit_attributes.conf with the information needed by the API:
api_key = rRKdgzCvPliUd2Hxa2k6Z3KCQzbgs8uSzjQpn2O4+62mEO9aEDTYJqcRhktODURB
api_id = gordon.sdsc.teragrid
resource_name = gordon.sdsc.teragrid
rest_url_base = https://xsede-xdcdb-api.xsede.org/
spool_file = /var/tmp/gateway_attributes_spool.txt
9) Edit sudoers to grant everyone permission to run gateway_submit_attributes under the gwsubmit account.
This can be done by adding these lines:
Defaults!/path/to/gateway_submit_attributes runas_default=gwsubmit
Defaults!/path/to/gateway_submit_attributes !requiretty
Defaults!/path/to/gateway_submit_attributes env_keep="USER"
ALL ALL=(gwsubmit) NOPASSWD:/path/to/gateway_submit_attributes
10) Run following tests as a non-privileged user for sanity-checks. ]
$ /gateway_submit_attributes \
-gateway_user \
-submit_time \
-jobid
Example with properly formatted parameters:
$ /usr/local/gateway/gateway_submit_attributes \
-gateway_user yuma@gateway.iu.edu \
-submit_time "2014-08-01 09:30:33-04:00" \
-jobid 538912
Results: Get the following success message:
Gateway attributes [ gateway_user = yuma@gateway.iu.edu ; submit_time = 2014-08-01 09:30:33-04:00 ; jobid = 538912 ] submitted successfully.
Some gateway_submit_attributes failures will result in a spool file entry that can’t be processed.
If this happens the application administrator will need to manually delete that entry from the spool file.
Some connection failures may be due to the client machine not recognizing the TLS/SSL
Certificate of the XDCDB API service. You can confirm if that is the problem you are
having by temporarily adding this line at the start of the gateway_submi_attributes script:
$ENV{PERL_LWP_SSL_VERIFY_HOSTNAME} = 0;
11) To facilitate incorporation of the target installation directory into
users' PATHs, install a modules file called gateway-submit-attributes.
See the gateway_submit_attributes.module.example file in this package.