Installing Fioctl

Fioctl™ is a simple tool for interacting with the Foundries.io™ REST API.

See also

Fioctl is based on Foundries.io’s ota-lite API.

Fioctl is used to manage:

Installation

Manual Installation

We use GitHub Releases to distribute static golang binaries.

Tip

Fioctl v0.36 and later has an auto-update feature. Run fioctl version to check for an update, then run fioctl version --update-to <version>. For more details checkout the Fioctl user guide.

Attention

Make sure you have curl installed.

  1. Download a Linux binary to a directory on your PATH.

    For example, to download version v0.40 on Linux, define the version:

    FIOCTL_VERSION="v0.40"

    Download the binary with curl:

    sudo curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-linux-amd64

  2. Make the Fioctl binary executable:

    sudo chmod +x /usr/local/bin/fioctl

Authenticating Fioctl

With Fioctl installed, authenticate it with our backend. For this, you will generate OAuth2 application credentials for interacting with the FoundriesFactory® API:

fioctl login
 Please visit:

 https://app.foundries.io/settings/credentials/

 and create a new "Application Credential" to provide inputs below.

 Client ID:

Fioctl will now ask for your Client ID and Secret. Follow the next steps to generate them.

Adding Application Credentials

Go to Application Credentials and click on + New Credentials.

../../_images/application_credentials.png

Fig. 6 Application Credentials

Complete with a Description and the Expiration date and select next.

For Fioctl®, check the Use for tools like fioctl box and select your Factory. You can revoke this access and set up a new credential later once you are familiar with the API Access.

../../_images/fioctl_token.png

Fig. 7 API Token

Tip

We recommend creating a new API token for each computer you plan to use our tools with. For example, if you intend to develop on both a laptop and a desktop, create a new token for each, as you would with SSH keys. This way you can revoke tokens for individual systems, should they be compromised.

Use the Client ID and Secret to finish the Fioctl login.

../../_images/token.png

Fig. 8 Client ID and Secret

fioctl login
 Please visit:

 https://app.foundries.io/settings/credentials/

 and create a new "Application Credential" to provide inputs below.

 Client ID:
 Client secret:
 You are now logged in to Foundries.io services.

The following command can be used to test the fioctl configuration.

fioctl -f <factory> status
  Total number of devices: 0
  TAG  LATEST TARGET  DEVICES  ON LATEST  ONLINE
  ---  -------------  -------  ---------  ------

  Orphan target versions below are marked with a star (*)

See also

Fioctl documentation.

Configuring Git

After Fioctl is properly setup, it can be leveraged as a Git credential helper to allow pushing to your repositories with FoundriesFactory®. With this, Git knows when you connect to source.foundries.io and uses Fioctl for authentication when utilizing git commands.

Setting Up Git

Run the following command to add the relevant entries to the Git configuration:

sudo fioctl configure-git

Important

This must run as sudo instead of directly as the root user. This is because it needs to have privileges to create a symlink in the same directory as where git is located.

Warning

  • If for some reason the command sudo fioctl configure-git fails with an error, manual steps can be taken to get the exact same result. For comprehensive instructions, please see the Fioctl™ Errors section.

  • Existing users reconfiguring Git access may need to remove the following lines from .gitconfig to use fioctl configure-git utility:

    [http "https://source.foundries.io"]
extraheader = Authorization: basic <TOKEN>

  • If editing scopes on existing tokens, the user should refresh the local fioctl credentials with:

    fioctl login --refresh-access-token

Verify this has succeeded by cloning a repository from your Factory, such as your containers.git repo. Replace <factory> with your Factory’s name:

git clone https://source.foundries.io/factories/<factory>/containers.git

Tip

You can also use git config --global --list to show the current state of the global Git configuration, where source.foundries.io should be referenced along with a username and a helper.

See also