trifid/docs/tfcli/getting_started.md

Getting Started Guide - tfcli

This guide will walk you through the process of setting up a new trifid-api organization and enrolling your first host, from scratch, using the trifid stack and a trifid-api server.

This guide assumes you already have a trifid-api server set up, but you have not created a user account or organization yet. If you have, the Quick Reference Handbook may be of more use to you.

If you don't have a trifid-api server set up, or need help configuring it, consider checking out the trifid-api Getting Started Guide or the trifid-api Quick Reference Handbook.

Installing tfcli

The first step to using tfcli is installing it. We recommend you do this via cargo, rust's package manager, as it is the most fool-proof way to quickly ensure that the program is installed correctly.

Run the following command:

cargo install tfcli

This will install the tfcli binary to your Cargo bin/ directory. You'll need to ensure that this directory is on your PATH - doing so is outside the scope of this guide.

Creating your account

The first step in setting up your trifid-api account is creating it! This, like all other tasks, can be done via the tfcli program. You'll need the following on hand:

• An email address (you don't need access to the mailbox though)
• Access to the trifid-api server logs to get the login token
• tfcli installed

In order to create an account, use the 'create account' tfcli command:

tfcli account create --email [INSERT_YOUR_EMAIL_HERE]

At this point, you'll need to check your trifid-api server logs. Look for a log message that looks like sent magic link [long-text-here that starts with 'ml-']. You'll need to grab the long string of characters starting with ml- and going to the end of the line. It'll look something like ml-NrrnaEm7N-6XqbDUweoNuwchI7SBCZwJQVPUDSS7T1g.

This token only remains valid for 10 minutes, so you'll need to move relatively quickly. If the token expires, don't worry - use the login command as described at the end of this section to get a new token.

Once you have your magic-link token, authenticate and create your session token:

tfcli account magic-link --magic-link-token [insert-long-string-of-characters-you-got-earlier]

This will get a special token from trifid-api that allows you to modify only your 2fa settings, but not any hosts, networks, or roles. tfcli automatically saves this token to your computer - you don't need to worry about it.

After this, you'll need to set up 2fa before you can do any other management tasks.

In addition, approximately once every year, your session token will expire. You might also want to use multiple computers. To do this, use the login feature instead of signup:

tfcli account login --email [INSERT_YOUR_EMAIL_HERE]

You can then use the magic-link command exactly as above to renew your session token or log in on a new PC.

Setting up 2FA

trifid-api enforces two-factor authentication on all accounts. You will be unable to perform any management tasks until you complete 2fa setup. You'll need:

• tfcli installed
• A valid account and session token as created in the previous step
• A TOTP-compatible authenticator like Authy or Google Authenticator

After you've logged in, run the following command to get your TOTP setup code:

tfcli account mfa-setup

This command will give you instructions on how to complete TOTP setup. Follow the directions given. Afterwards, an auth token will be issued by trifid-api and saved to your computer that gives you full control over your trifid-api resources such as networks, hosts, and roles.

This token expires after about 10 minutes. When it expires, you'll need to generate a new one by entering the code on your TOTP authenticator that you set up earlier into the following command:

tfcli account mfa --code [CODE_IN_AUTHENTICATOR_APP]

This will issue another token that is valid for another 10 minutes.

Troubleshooting 'Unauthorized' messages

If you ever see error messages about being 'unauthorized', it most likely means your authentication token has expired, and you need to run tfcli account mfa again. If you try that and it is successful, but you still see errors, or if tfcli account mfa itself gives you an "Unauthorized error", it means your session token has expired. Refer to the end of 'Creating your Account' above to learn how to log in again. After getting a new session token you will always need to get a new TOTP token.

If, even after renewing your session and authentication tokens, you are still getting 'Unauthorized', it is likely an issue with your server setup. Check the trifid-api server logs or the logs of your proxy and ensure that there are no additional setup issues.

If you're still having issues, shoot a message to our mailing list on the homepage of this documentation and we would be glad to help you out.