How to Upload Files to Cases Using Red Hat Secure FTP
Disclaimer: Links contained herein to external website(s) are provided for convenience only. Red Hat has not reviewed the links and is not responsible for the content or its availability. The inclusion of any link to an external website does not imply endorsement by Red Hat of the website or their entities, products or services. You agree that Red Hat is not responsible or liable for any loss or expenses that may result due to your use of (or reliance on) the external site or content.
Table of Contents
- 1. Background
- 2. Scope
- 3. User Guide for Customers
1. Background
As outlined in the article Red Hat Support Tool, RHST, Deprecation Guide the redhat-support-tool has been deprecated as of RHEL 9. This article walks customers through how to use Red Hat Secure FTP, Red Hat's new Secure FTP service, to upload files to cases.
The purpose of Red Hat Secure FTP is to provide a sustainable, cross-platform and command-line accessible endpoint for customers to upload files to Red Hat. The goal is to provide a secure, scalable endpoint that is usable across the broad customer base.
2. Scope
- Provide an endpoint accessible by customers for uploading files from command-line
- Minimal disruption to customer workflow
- No additional packages by Red Hat
- Secure Support cases are OUT OF SCOPE
3. User Guide for Customers
3.1 Authenticated Flow
Customers having valid portal credentials should be able to upload an attachment to a case of an account to which they belong, however, there is a strict file format policy (i.e ${CASEID}_* or sosreport-${CASEID}-*) which needs to be followed. If the filename is valid, the file would be uploaded to case as an attachment and deleted from the Red Hat Secure FTP, however, if the filename is invalid, it remains in the Red Hat Secure FTP bucket for 30 days, after which it is permanently deleted.
Here are a few example filenames with valid and invalid formats for automatic attachment to support cases:
- sosreport-hostname-4-02855523-2021-04-20-uhbkfag.tar.xz (Valid) [default filename generated by
sosreport] - 02436811_sosreport-12387183.gz (Valid)
- 02436811_log-report.txt (Valid)
- 02436811-sosreport.gz (Invalid)
- sosreport.gz (Invalid)
- sosreport_02436811.gz (Invalid)
- sosreport-02855523-testreport.gz (Valid)
- sosreport_02855523-testreport.gz (InValid)
- sosrep_02855523-testreport.gz (InValid)
- 02855523-testreport.gz (InValid)
- 02855523_testreport.gz (Valid)
The below matrix explains what an authenticated customer is entitled to do:
| Can | Cannot |
|---|---|
| List files in their own directory | List/view other user's files or directories |
| Upload an attachment to Red Hat SFTP, and with the correct filename format auto attach the file to a support case the customer has access to | Download any attachment |
| Attach files to cases they don't have access to |
Note: If the uploaded file is prefixed with an invalid case number or a case number that the customer doesn't have access to, the uploaded file will not be attached to the support case, and will remain in Secure FTP as per the retention policy.
Here's a quick walkthrough for uploading an attachment.
3.1.1 Token Generation
3.1.1.1 Using cURL
Open a command terminal (on Linux or Macintosh) or PowerShell (on Windows). At the prompt, use the cURL commands as detailed below to log into your customer portal account and grant permission to fetch an access token to be used generate an SFTP login token.
Device Authorization:
First step in generating an SFTP login token is to verify your customer portal account and grant access to fetch a bearer token to be used to authenticate while generating an SFTP login token. More details on device authorization flow can be found here.
Enter the following curl -
$ curl --request POST 'https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/auth/device' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=hydra-sftp'
{
"device_code": "Zq8vFKGMrIONm3HeWRrXnV9PQgkwDiydhFtKcOVm32w",
"user_code": "EYWJ-TDJH",
"verification_uri": "https://sso.redhat.com/auth/realms/redhat-external/device",
"verification_uri_complete": "https://sso.redhat.com/auth/realms/redhat-external/device?user_code=EYWJ-TDJH",
"expires_in": 600,
"interval": 5
}
Now visit the verification_uri_complete in a browser. Alternatively, open the verification_uri in a web browser and submit the value of user_code as requested.
Next, log in to your customer portal account when prompted and grant permission to the hydra-sftp client. Once access has been successfully granted, copy the device_code from the previous response and proceed to the next step.
v2 API (Configurable Token validity 0-90 days):
Token Generation v2 API gives users the flexibility to configure the token expiry date. The 'expiryInDays' parameter accepts values in days from 0 days to maximum of 90 days. Default value of 'expiryInDays' is 30 days.
Enter the below commands in your terminal (replace the device_code value with the one obtained from the above response).
- Sample curl for token generation with default expiry date (30 days):
$ bearer_token=$(curl -s --request POST 'https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=hydra-sftp' --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' --data-urlencode 'device_code=Zq8vFKGMrIONm3HeWRrXnV9PQgkwDiydhFtKcOVm32w' | jq -r '.access_token')
curl --header "Authorization: Bearer $bearer_token" --request POST 'https://access.redhat.com/hydra/rest/v2/sftp/token'
{"username": "brett.lymn","token": "SBmaGUbA","expiryDate": "2021-8-01T06:37:19.966Z"}
- Sample curl for token generation with 'expiryInDays' as 60 Days
$ bearer_token=$(curl -s --request POST 'https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=hydra-sftp' --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' --data-urlencode 'device_code=Zq8vFKGMrIONm3HeWRrXnV9PQgkwDiydhFtKcOVm32w' | jq -r '.access_token')
curl --header "Authorization: Bearer $bearer_token" --request POST 'https://access.redhat.com/hydra/rest/v2/sftp/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"expiryInDays" : 60
}'
{"username": "brett.lymn","token": "SBmaGUbA","expiryDate": "2021-10-01T06:37:19.966Z"}
v1 API (Token validity fixed at 30 days):
$ bearer_token=$(curl -s --request POST 'https://sso.redhat.com/auth/realms/redhat-external/protocol/openid-connect/token' --header 'Content-Type: application/x-www-form-urlencoded' --data-urlencode 'client_id=hydra-sftp' --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' --data-urlencode 'device_code=Zq8vFKGMrIONm3HeWRrXnV9PQgkwDiydhFtKcOVm32w' | jq -r '.access_token')
curl --header "Authorization: Bearer $bearer_token" https://access.redhat.com/hydra/rest/v1/sftp/token
{"username" : "brett.lymn", "token" : "7c8afc4f","expiryDate": "2021-8-01T06:37:19.966Z"}
3.1.1.2 Using Web UI (uses v1 APIs):
Alternatively, using a web browser, go to the Red Hat Secure FTP Token Generator application and log in using Customer Portal credentials. Then click on "Generate Token" to generate a new token or view an existing valid token.
Note:
- The v1 API returns an existing token if present and updates the expiry date of token by $CURRENT_DATE + 30 days.
- If an existing token is not found, then a new token is generated with an expiry of 30 days.
- v1 API will be deprecated soon, so make sure you migrate your scripts/guides to use the v2 API.
- The v2 API uses the POST method instead of GET.
- The value for 'expiryInDays' should be more than or equal to 30 (anything between 0 to 30 will be treated as 30) and less than or equal to 90 (any value more than 90 will result in a validation error).
- Basic Authetication / Direct Password grants will be (or has been, depends on when you read this) deprecated from 1st December, 2023.
3.1.2 SFTP Connection
3.1.2.1 On Linux or Macintosh
From a command terminal, open the SFTP connection and enter the token when prompted for password:
$ sftp brett.lymn@sftp.access.redhat.com
brett.lymn@sftp.access.redhat.com's password: <token>
Connected to brett.lymn@sftp.access.redhat.com.
sftp>
3.1.2.2 On Windows
Users can use the winscp software to connect from a windows machine.
3.1.3 Attachment Upload
3.1.3.1 On Linux or Macintosh
Uploading a file to case using PUT command using ${CASEID}_* format.
sftp> put 02436811_sosreport.gz
Uploading 02436811_sosreport.gz to /02436811_sosreport.gz
02436811_sosreport.gz 100% 10MB 1.9MB/s 00:05
sftp>
3.1.3.2 On Windows
Use the winscp software to upload files from a windows machine.
Note
- If the filename is in the correct format of
${CASEID}_*:
- the file will get attached to its corresponding case.
- if the file was successfully attached to a case, it is removed from Secure FTP and will no longer be visible there.
- If the filename is not in the correct format:
- the file will not get attached to a case.
- the file will remain in Secure FTP as per the retention policy.
- If there are special character in username like 'example@company.com', the above steps should still work.
- Uploads over Secure FTP are single stream, as compared to the multi-part upload capability that Customer Portal Case Management provides. This could result in slower speeds during SFTP uploads.
Examples of special characters in username:
$ curl --header 'Authorization: Bearer <bearer_token>' https://access.redhat.com/hydra/rest/v1/sftp/token
{ "username" : "example@company.com", "token" : "7c8afc4f", "expiryDate" : "2021-09-07T10:13:46.149Z" }
$ sftp example@company.com@sftp.access.redhat.com
example@company.com@sftp.access.redhat.com's password: <token>
Connected to example@company.com@sftp.access.redhat.com
sftp>
3.2 Unauthenticated Flow
Red Hat SFTP also supports file uploads by users who do not have an account created with Red Hat. They will be able to upload a file to Red Hat SFTP and view the files present under their directory, however they won't be able to download any file. Also, files uploaded by anonymous users aren't auto-attached to a support case.
The below matrix explains what an anonymous user is entitled to do:
| Can | Cannot |
|---|---|
| List files in their own directory | List/view other user's files or directories |
| Upload an attachment to Red Hat SFTP | Download any attachment |
| Attach files to a support case |
3.2.1 Username and Token generation
Open a command terminal (on Linux or Macintosh) or PowerShell (on Windows). At the prompt, enter the following cURL to generate username and token for anonymous user:
v2 API
$ curl --request POST 'https://access.redhat.com/hydra/rest/v2/sftp/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"isAnonymous" : true
}'
{"username" : "aiFPyJiK", "token" : "FAAivaiy", "expiryDate" : "2021-09-07T10:13:46.149Z"}
v1 API
$ curl https://access.redhat.com/hydra/rest/v1/sftp/token?isAnonymous=true
{"username" : "DpDPSPGN", "token" : "89d41439", "expiryDate" : "2021-09-07T10:13:46.149Z"}
Alternatively, using a web browser, go to the Red Hat Secure FTP Token Generator application and log in as Guest. Then click on "Generate Token" to generate a new username and token.
Note: Anonymous tokens are valid for one time use only. For every session, a new token needs to be generated.
3.2.2 SFTP connection
Connect to Red Hat SFTP (refer to Authenticated flow for WinSCP).
$ sftp DpDPSPGN@sftp.access.redhat.com
DpDPSPGN@sftp.access.redhat.com's password: <token>
Connected to DpDPSPGN@sftp.access.redhat.com.
sftp>
3.2.3 File upload
Upload file using PUT command (refer to Authenticated flow for WinSCP).
Connected to DpDPSPGN@sftp.access.redhat.com.
sftp> put sysreport.tar.gz
Uploading sysreport.tar.gz to /sysreport.tar.gz
sysreport.tar.gz 100% 10MB 1.8MB/s 00:05
sftp>
3.2.4 File listing
List file under user's directory. This can also be done using WinSCP.
sftp> ls -l
-rwxr--r-- 1 - - 10485760 Sep 30 18:18 sysreport.tar.gz
sftp>
3.3 Connecting to Secure FTP server via proxy
A alternative method for connecting to sftp server via proxy
3.3.1 Unauthenticated proxy (RHEL 8 and RHEL 7)
sftp -o "ProxyCommand nc --proxy <proxy_host>:<proxy_port> --proxy-type http %h %p" brett.lymn@sftp.access.redhat.com
3.3.2 For authenticated proxy (RHEL 8 and RHEL 7)
sftp -o "ProxyCommand nc --proxy <proxy_host>:<proxy_port> --proxy-auth <proxy_user>:<proxy_password> --proxy-type http %h %p" brett.lymn@sftp.access.redhat.com
3.3.3 For authenticated proxy (RHEL 8 and RHEL 7) but using Port 80.
sftp -P 80 -o "ProxyCommand nc --proxy <proxy_host>:<proxy_port> --proxy-auth <proxy_user>:<proxy_password> --proxy-type http %h %p" brett.lymn@sftp.access.redhat.com
3.3.4 For RHEL 6
Please use the ncat command instead of nc. E.g.
sftp -o "ProxyCommand ncat --proxy <proxy_host>:<proxy_port> --proxy-type http %h %p" brett.lymn@sftp.access.redhat.com
Note -
1. The proxy needs to be configured for this example to allow port 22 OR port 80 in proxy config, so that it can connect to Secure FTP.
2. You need to install the package that provides nc command i.e nmap-ncat (sudo yum install nmap-ncat for RHEL 7 and RHEL 8) . For RHEL 6, you need to install the package nmap (sudo yum install nmap) .
3.4 Retention Policy
The default retention policy for Red Hat Secure FTP is 30 days. Post 30 days, the files are deleted permanently. This is not the case for file uploaded with a valid support case number prefix (${CASEID}_*) in which case files are deleted immediately after it is successfully attached to the support case.
Once a file is attached to a support case, they are retained for 3 years.
3.5 Customer Firewall Configuration
Your customer must allow these connections in their firewall:
| Source | Destination | Purpose |
|---|---|---|
| Customer IP | sftp.access.redhat.com:22 OR 35.80.245.1:22 | SFTP control channel |
OR
| Source | Destination | Purpose |
|---|---|---|
| Customer IP | sftp.access.redhat.com:80 OR 35.80.245.1:80 | SFTP control channel |
Note:
1. Connections are supported over both Port 22 and Port 80.
2. The IP Address 35.80.245.1 can be used in place of the hostname sftp.access.redhat.com in proxy / firewall config, but this IP might change if we update the load balancer.
3. Additionally, please open access to access.redhat.com:80 to your firewall configuration, in case the token generation is performed on the same machine as the SFTP uploads.
3.6 SSH Host Key Fingerprint
Here's the fingerprint of the SSH host key for Red Hat Secure FTP:
SHA256:Ij7dPhl1PhiycLC/rFXy1sGO2nSS9ky0PYdYhi+ykpQ=
3.7 Wrapper script to help with SFTP uploads
We have attached a wrapper shell script to this article which can be used to upload files directly to Red Hat Secure FTP. Please note that this is not to be treated as a Red Hat official binary / software, and feel free to go though the source code to look for what's happening behind the scenes. Also note that this script works on Linux and MacOS (tested on RHEL 8, RHEL 7 and MacOS, with the caveat that there is an issue with unauthenticated proxy on RHEL 7).
After downloading, you may unzip and run the script with --help option to see all the available command line options.
$ unzip uploadfiletosftp.zip
$ cd uploadfiletosftp/
$ sh uploadFileToSFTP.sh --help
DESCRIPTION:
This wrapper script eliminates the multiple commands needed to be typed manually by the user to upload a file to SFTP. It takes the file path for the file to be uploaded and then performs all the steps from authentication to uploading the file to SFTP. The user should note that the script makes use of v2 API for SFTP token generation.
SYNTAX: sh uploadFileToSFTP.sh [--path file_path] [-C case_number] [--proxy proxy_type] [-x proxy_user] [-y proxy_password] [-h proxy_host] [-o proxy_port] [-c] [-b] [--help]
OPTIONS:
--path The --path option is a mandatory option, whose option argument is used to specify
the complete file path of the file to be uploaded.
-C | --case If the -C option is present, the corresponding option argument is used to specify the
case number to which the file is to be attached.
-x | --proxy_user If the -x option is present, the value for the proxy_user in the properties.json
file is set as the corresponding option argument.
-h | --proxy_host If the -h option is present, the value for the proxy_host in the properties.json
file is set as the corresponding option argument.
-o | --proxy_port If the -o option is present, the value for the proxy_port in the properties.json
file is set as the corresponding option argument.
-y | --proxy_password If the -y option is present, the corresponding option argument is used to specify
the proxy_password of proxy_user. If your password contains any special character,
you must enclose the 'password' in single quotes.
-c | --config_all If the -c option is present, it will trigger input prompts for configuring each
property in properties.json file, enabling the user to set or change value for
any property.
--proxy If the --proxy option is present, the corresponding option argument is used to specify
the type of proxy to be used to connect to connect to SFTP. For authenticated proxy,
provide the option argument as 'auth' and 'unauth' for an unauthenticated proxy
connection. Any other value shall default to connect to SFTP without any proxy.
-b | --sso_token If the -b option is present, the script will print the bearer token corresponding to the
customer portal account of the user and exit.
--help Print this help and exit.
Obtaining Bearer token for your Customer Portal account:
The SFTP wrapper script also serves the purpose of acquiring an access token for your customer portal account. This access token can be subsequently utilized as a bearer token during the generation of the SFTP login token.
Execute the script in the following manner to display the access token:
$ sh uploadfiletosftp.sh -b
{"access_token":"XXXX","expires_in":900,"refresh_expires_in":36000,"refresh_token":"XXXX","token_type":"Bearer","not-before-policy":0,"session_state":"88bd2a9e-8048-4440-bac1-772735788bad","scope":"Legacy_IDP_OpenID"}
Comments