Skip to content
English
  • There are no suggestions because the search field is empty.

What are alternative methods for file transfers with Xona?

The easiest method of file transfer in Xona is through the web interface, but sometimes this is not available for certain remote systems. The web interface requires a modern browser, and this can be problematic for Windows systems with only Internet Explorer (IE) and Linux systems with command line interfaces over SSH. This article describes alternatives that can work for these types of systems.

Primary Options

The primary methods for file transfer in Xona are described in the main documentation:

  1. The file listing for the File Bucket in Xona: https://docs.xonaengineering.io/5.5.1/docs/Admin-Guide/Files/#viewing-bucket-files

  2. Magic links through a modern web browser: https://docs.xonaengineering.io/5.5.1/docs/Admin-Guide/Files/#magic-link-address-customization
  3. Server Message Block (SMB) integration: https://docs.xonaengineering.io/5.5.1/docs/Admin-Guide/Files/SMB-Integration

File transfer over SMB

Server Message Block (SMB) is a common file transfer protocol found in a wide variety of systems, especially Windows, where it is natively supported (i.e., a "Windows file share") and serves as the basis for many basic functions in key software like Active Directory. SMB is the most flexible and streamlined option for file transfer for Xona. CSGs can synchronize the contents of file buckets with an SMB service, which could be running on a dedicated Network Attached Storage (NAS) server or directly on the remote server that Xona connects to.

SMB is not only an option for Windows. Many Linux systems have Samba packages available for installation. Samba brings SMB functionality to Linux, enabling SMB share functionality that a Xona CSG can synchronize with.

Prerequisites

  • Network connectivity from the Xona CSG to the SMB service over SMB (tcp/445).

  • Login credentials for the SMB service (assuming it is authenticated).

Procedure

There is no single procedure for implementing SMB for file transfer because SMB services are platform-dependent. Consult your platform documentation for guidance on how to implement SMB in accordance with recommended best practices.

The Xona CSG can be integrated with an SMB service by following the documentation here:

Directions on enabling the SMB service are widely available for common operating systems, however, they vary depending on the platform.

Resources for Microsoft Windows:

Resources for Red Hat Enterprise Linux (applies to Red Hat derivatives like CentOS and Fedora):

General Samba Documentation:

File Transfer via wget on the CLI

The wget CLI program is very common in Linux environments. It is possible to use wget together with upload links and download links from Xona. Typically, wget comes installed out-of-the-box on Linux systems.

Prerequisites

  • Network connectivity from the remote host to the Xona CSG over HTTPS (tcp/443).

  • Access to a command line environment on the remote host, most commonly a Linux host using SSH.
  • Ability to run wget from the command line.

Procedure

Downloads

The following wget command will download a file from the Xona device [xona] with the sample download link https://[xona]/dl?s=79Fb7cQFa5Ir9lWrTnNsZD . Run this command using the correct download link from your Xona device.

wget --content-disposition 'https://[xona]/dl?s=79Fb7cQFa5Ir9lWrTnNsZD'
Uploads

The following commands will upload a file to the Xona device [xona] with the upload link example https://[xona]/v1/files/upload-links/upload?s=NLXRv5mp1GZ2Vbn94YaG2D .

There are four commands involved:

  1. The first command creates a FILE vairable and sets it to example.txt, which is the the name of the file we want to upload.

  2. The second command creates a SIZE variable and sets it to the output of the wc command, which should compute the size of the example.txt file in bytes.
  3. The third command runs wget with arguments to specify the upload link URL, the file size ($SIZE), and the file name ($FILE).

Make sure to use the correct upload link and file name when running these commands.

FILE=example.txt
SIZE=$(wc -c <example.txt)
wget \
  --method=POST \
  --header="Content-Length: $SIZE" \
  --header="Content-Disposition: attachment; filename=\"$FILE\"" \
  --body-file="$FILE" \
  -O- \
  'https://[xona]/v1/files/upload-links/upload?s=NLXRv5mp1GZ2Vbn94YaG2D'

File Transfer via curl on the CLI

The curl CLI program is a popular tool for Linux environments. It is possible to use curl together with upload links and download links from Xona. The curl program provides more advanced options compared to wget, but it is typically not installed by default. 

Prerequisites

  • Network connectivity from the remote host to the Xona CSG over HTTPS (tcp/443).

  • Access to a command line environment on the remote host, most commonly a Linux host using SSH.
  • Ability to run curl from the command line.

Procedure

Downloads

The following curl command will download a file from the Xona device [xona] with the sample download link https://[xona]/dl?s=79Fb7cQFa5Ir9lWrTnNsZD . Run this command using the correct download link from your Xona device.

curl -O -J 'https://[xona]/dl?s=79Fb7cQFa5Ir9lWrTnNsZD'
Uploads

The following commands will upload a file to the Xona device [xona] with the upload link example https://[xona]/v1/files/upload-links/upload?s=NLXRv5mp1GZ2Vbn94YaG2D .

There are four commands involved:

  1. The first command creates a FILE vairable and sets it to example.txt, which is the the name of the file we want to upload.

  2. The second command creates a SIZE variable and sets it to the output of the wc command, which should compute the size of the example.txt file in bytes.
  3. The third command runs curl with arguments to specify the upload link URL, the file size ($SIZE), and the file name ($FILE).

Make sure to use the correct upload link and file name when running these commands.

FILE=example.txt
SIZE=$(wc -c <example.txt)
curl -v \
  -X POST 'https://[xona]/v1/files/upload-links/upload?s=NLXRv5mp1GZ2Vbn94YaG2D' \
  -H "Content-Length: $SIZE" \
  -H "Content-Disposition: attachment; filename=\"$FILE\"" \
  --data-binary @"$FILE"

File Transfer via Xona CLI Tool

The Xona CLI Tool xonactl (aka "Xona Control) is provided with every Xona device. The Xona CLI Tool interacts with the Xona REST API to perform many of the same operations that are possible from the web interface. File bucket operations, including uploads and downloads, are possible with the xonactl CLI program.

Prerequisites

  • Browser access to the Xona CSG over HTTPS (tcp/443).

  • Login credentials for a Xona user with:
    • The API system-level permission.
    • The file bucket permission for uploads and downloads.
  • Ability to run programs from a command prompt or terminal interface on the remote system.
  • Ability to use the Clipboard from the remote session within Xona.

Procedure

Setup for API access

  1. From your web browser, access the Xona CSG login page using a web browser.

  2. From your web browser, login with a user who has the permissions described in Prerequisites.
  3. From your web browser, right-click on the documentation link to open a new tab so you can reference the CLI tool documentation. The documentation section is also publicly available. For example, see the v5.5.1 documentation at this link: https://docs-test.xonaengineering.io/5.5.1/docs/CLI/Getting-Started
  4. From your web browser's Xona tab, navigate to the Profile button at the bottom-right side of the screen. Scroll down to the API Key / SSH Key sections.
  5. Create an authentication key for your admin user to authenticate with the CLI tool. Use one of the options below.
    1. From your web browser's CSG tab, generate an API Key for your admin user to authenticate with the CLI tool.
      1. This option is ideal when a single CSG is involved.
    2. From your computer's command prompt/terminal, generate an SSH key on your computer (ssh-keygen), open the public key file, and save the public key file contents in Xona. 
      1. This option is ideal when multiple CSGs are involved.
  6. From your web browser's CSG tab, save the key in the user's Profile.

  7. From your web browser, navigate to "Help" towards the bottom of the main menu to access both documentation and download links for the Xona CLI tool (xonactl).

  8. Copy the download link to your clipboard.
  9. Start a connection to your remote system in Xona.
  10. Enable the clipboard in your remote session in Xona.
    1. The clipboard can be toggled from the Xona menu visible on the side of the screen.
  11. Use the download link to the xonactl CLI tool to download it to your remote system. Depending on your remote system's connectivity, it the link may need to be edited to use the local IP address for your CSG.
    1. The xonactl download may be accessed through a browser, like Internet Explorer (IE).
    2. The xonactl download may be accessed via CLI tools like wget and curl.
  12. From the remote system's downloads folder, extract the ZIP file to a directory where you can run xonactl.
    1. The user's home directory is typically the best place for the Xona CLI tool because this is the default location for the Windows command prompt sessions and Linux terminal sessions.
    2. To extract the ZIP file on the Linux command line, the unzip CLI program can be used.
  13. From the remote system's command prompt/terminal, navigate to the directory where xonactl was saved, then run it once without any arguments.
    1. It should print out a list of available subcommands.
    2. If after several seconds there is no output, or an error message appears:
      1. Check that the Xona CLI tool matches your computer's OS and CPU architecture.
      2. Check that the Xona CLI tool is not being blocked by some OS configuration or software.
  14. Switch to your web browser's documentation tab and refer to the "Getting Started" part of the CLI documentation section (for example, https://docs-test.xonaengineering.io/5.5.1/docs/CLI/Getting-Started). Complete the steps in that documentation section useng the remote system's command prompt/terminal. Proceed with the next steps after a successful login.
    1. If xonactl is authenticating to the Xona device with an IP address, or there is not a trusted HTTPS certificate for the Xona device, then xonactl commands will need to be run with a -i option at the end. This option tells the Xone CLI tool to ignore certificate warnings.
  15. To download a file using xonactl, use the following command, where [bucket-id] matches the file bucket id in Xona, the [file-id] matches the file ID in Xona, and the [download-dir] points to the location where the file should be saved: 
    1. xonactl files download [bucket-id] [file-id] [download-dir]
  16. To upload a file using xonactl, use the following command, where [bucket-id] matches the file bucket id in Xona, and [file-path] matches the filesystem path to the file: 
    1. xonactl files upload [bucket-id] [file-path]
  17. Logout from the Xone CLI tool session with the following command:
    xonactl login logout 

Additional Information

Unsure if this is required for your Xona deployment? Please reach out to support@xonasystems.com and we would be happy to discuss it with you.