core
/
trifid
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects 7 Releases Wiki Activity

[docs] remove old docs

This commit is contained in:
core 2023-10-06 22:27:48 -04:00
parent be14179c2d
commit 11a37ff909
Signed by: core
GPG Key ID: FDBF740DADDCEECF
8 changed files with 0 additions and 311 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
docs/tfcli/getting_started.md
View File

@ -1,91 +0,0 @@
# 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](docs/tfcli/qrh.md) 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](docs/trifid-api/getting_started.md) or the [`trifid-api` Quick Reference Handbook](docs/trifid-api/qrh.md).
## 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:
```shell
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:
```shell
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:
```shell
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`:
```shell
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:
```shell
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:
```shell
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](index.md) of this documentation and we would be glad to help you out.

17
docs/tfcli/index.md
View File

@ -1,17 +0,0 @@
# tfcli
`tfcli` is a command-line interface for managing trifid-api compatible API servers.
<div class="alert alert-warning">
<strong>Notice</strong>: `tfcli` does not implement a DNClient-compatible VPN client. It only allows management. For a VPN client, check out tfclient instead.
</div>
`tfcli` is a feature-complete comand-line client and supports all features that `trifid-api` does, including some feature additions not available on the normal Defined Networking client.
## Getting Started
Please check out the [Getting Started Guide](docs/tfcli/getting_started.md) to learn how to create a organization from scratch and enroll your first host using the `tfcli` program.
## Quick Reference Handbook
Check out the [quick reference handbook](docs/tfcli/qrh.md) with a listing of all commands available on `tfcli`.

89
docs/tfcli/qrh.md
View File

@ -1,89 +0,0 @@
# `tfcli` Quick Reference Handbook
## Configuring the Server URL
`tfcli` needs a server URL to be able to contact the API server. This can be configured in three ways, from most optimal to least optimal:
1. The file in `$CONFIG/tfcli-server-url.conf` can have it's contents set to the base URL of the server you would like to use
2. You can set the environment variable `TFCLI_SERVER` to the base URL
3. You can provide the `-s/--server` argument immediately after `tfcli`, before your management command. For example: `tfcli --server https://your-server.your-domain.com network list`
## Account Management
These commands provide a means of managing your account and credentials on the `trifid-api` server.
### Create Account
Create a new account on the designated server.
**Usage:** `tfcli account create --email <EMAIL>`
### Log Into Existing Account
Log into an existing account on the designated server.
**Usage:** `tfcli account login --email <EMAIL>`
### Authenticate with Magic Link Token
Log into your account with a magic-link token acquired via email or the trifid-api logs
**Usage:** `tfcli account magic-link --magic-link-token <MAGIC_LINK_TOKEN>`
### Setup TOTP
Create a new TOTP authenticator on this account to enable authorizing with 2fa and performing all management tasks
**Usage:** `tfcli account mfa-setup`
### Finish setting up TOTP
Finish creating a new TOTP authenticator by inputting the code shown on your authenticator app
**Usage:** `tfcli account mfa-setup-finish --code <CODE> --token <TOKEN>`
### Authenticate with TOTP
Create a new short-lived authentication token by inputting the code shown on your authenticator app
**Usage:** `tfcli account mfa --code <CODE>`
Re-run this command if you get an "Unauthorized" error.
## Network Management
### List Networks
### Lookup Network
## Organization Management
### Create organization
## Role Management
### Create role
### List roles
### Lookup role
### Delete role
### Update role
## Host Management
### Create host
### List hosts
### Lookup hosts
### Delete host
### Update host
### Block host
### Enroll/re-enroll host

18
docs/tfclient/index.md
View File

@ -1,18 +0,0 @@
# tfclient - a Rust DNClient alternative
tfclient is an open-source Rust client for the Defined Networking "Managed Nebula" product. It is compatible with third-party servers and can be used in all the ways that normal dnclient can be used.
## Platform support
tfclient is supported on [most platforms](https://hub.e3t.cc/~core/trifid/#supported-platforms). tfclient is broken up into two "support tiers":
- 'Tier 1' platforms have full support, including linking to and managing the nebula binary. No extra work is required on these platforms - just install tfclient and run!
- 'Tier 2' platforms cannot link to the nebula-ffi CGo binary due to platform limitations. On these platforms, tfclient must be compiled in [Tier 2 mode](docs/tfclient/tier-2-building.md), and the user is responsible for managing the Nebula binary and ensuring it points to the tfclient-managed config file. Documentation on how to use tfclient on Tier 2 platforms can be found [here](docs/tfclient/tier-2-building.md)
On platforms marked 'untested', the trifid maintainers were unable to test tfclient on that platform. Help is wanted to test tfclient on as many platforms as possible!
tfclient [should work on most platforms](docs/tfclient/why_not_this_os.md), but the authors of tfclient don't have every device and OS combo in the world.
If you are willing to run untested software on your machine to contribute to trifid, consider [testing tfclient on your device](docs/tfclient/untested_os.md) and [reporting your findings back to us](https://lists.e3t.cc/~core/trifid-devel). This is super helpful to us and helps us maintain trifid for more platforms when we have users willing to test the latest versions and report bugs to us. If you are interested, please see [this page](docs/tfclient/untested_os.md).
Unfortunately, [tfclient won't work everywhere](docs/tfclient/why_not_this_os.md). See [here](docs/tfclient/why_not_this_os.md) for details.

11
docs/tfclient/mobile.md
View File

@ -1,11 +0,0 @@
# Why can't trifid work on mobile devices?
Mobile devices are tricky to support. Defined Networking maintains an app known as [Mobile Nebula](https://github.com/DefinedNet/mobile_nebula) to bring support for Defined Networking networks and Nebula to Android and iOS. Why can't we just fork this and add trifid support?
Well, [we did](https://github.com/c0repwn3r/trifid_mobile). This fork is known internally as trifid_mobile, and adds trifid support to the mobile_nebula app. Unfortunately the Defined Networking team is not willing to upstream these changes, which is a major roadblock due to the expensive licencing and publishing cost for mobile apps.
That is to say, mobile support is currently stalled due to lack of funding to make it work. While we'd love to introduce support on mobile platforms it is too complicated and expensive to dedicate team time to work on.
If you are a third-party developer with an Apple Developer account and are willing to lend it to publish a trifid_mobile fork, *or* you're a Defined Networking team member that would like to work with us to merge custom URL support into upstream mobile_nebula, please [get in touch directly](mailto:core@e3t.cc) and we can work something out.
For now, trifid cannot support mobile devices :(

13
docs/tfclient/untested_os.md
View File

@ -1,13 +0,0 @@
# Help us out - test tfclient on new platforms
There are [lots](index.md#where-does-trifid-work) of operating systems in which `tfclient` *should* work, but due to a lack of devices, it cannot be tested. If you have a system running one of these devices and want to help out the project, please test tfclient for functionality on your device!
<div class="alert alert-warning">
<strong>Notice</strong>: While tfclient is almost always perfectly safe, there are always risks to running untested software on production machines. Be careful out there!
</div>
If you aren't able to get tfclient to compile with nebula-ffi, consider trying it as a [Tier 2 platform](docs/tfclient/tier-2-building.md). Documentation on how to do this can be found [here](docs/tfclient/tier-2-building.md).
Any findings, positive or negative, can be posted straight to [trifid-devel](https://lists.e3t.cc/~core/trifid-devel).
Thanks! We really appreciate it.

11
docs/tfclient/why_not_this_os.md
View File

@ -1,11 +0,0 @@
# Why cant tfclient support XXXXX?
There are limits to what operating systems and architectures tfclient can support. As you may know, tfclient is based upon the [Nebula](https://github.com/slackhq/nebula) project, maintained by Slack and Defined Networking. tfclient can only support architectures and operating systems that [Nebula itself supports](https://github.com/slackhq/nebula/releases/).
In addition, tfclient, being written in Rust, can only function in environments [where Rust compiles well](https://doc.rust-lang.org/nightly/rustc/platform-support.html). For example, this rules out MIPS - `rustc` currently does not function correctly on that architecture, and thus tfclient cannot, and likely never will support that architecture.
Finally, tfclient generally requires a functioning CGo compiler, in order to properly link to Nebula. If this is not available, but tfclient itself compiles fine, this is known as a 'Tier 2' platform - you must compile and run Nebula separately, and tfclient will be unable to manage it other than providing it's config.
Did Nebula add a new architecture, and we missed it? Rust supports a new architecture in a new release? [Let us know!](https://lists.e3t.cc/~core/trifid-devel) We love adding support for new systems whenever we can.
Did we miss an architecture? If your architecture is supported by Nebula, Rust, and CGo, but you still get linking errors or segfaults when trying to build tfclient, we might have missed you - [get in touch](https://lists.e3t.cc/~core/trifid-devel) and we will work with you to get your system supported :D

61
index.md
View File

@ -1,61 +0,0 @@
# trifid
trifid is an open-souce reimplementation of the [Defined Networking](https://defined.net) management protocol for [Nebula](https://github.com/slackhq/nebula) networks.
It includes a reimplementation of the [API Server](https://api.defined.net), the [Web UI](https://admin.defined.net), `dnclient`, `nebula-cert` and `dnapi` - all fully API-compatible with the original versions.
We also include a Rust library for interacting with keys and certificates in the Nebula PKI. Find it in `trifid-pki/`, or on crates.rs as `trifid-pki`.
In addition, a command-line interface for the Defined Networking management API is included, `tfcli`.
Want to make your own Defined Networking client? Check out `dnapi-rs`! `dnapi-rs` is a Rust port of the official `dnapi` Go library, to allow for easy interactions with Defined Networking-compatible API servers. Find it in `dnapi-rs/`, or on crates.rs as `dnapi-rs`.
The API implementation is tested with the official dnclient implementation, and the dnclient implementation is tested with the official API server, to ensure complete feature parity between the two.
# Links
- [tfcli documentation](./docs/tfcli/index.md)
- [tfclient documentation](./docs/tfclient/index.md)
- [trifid-api documentation](./docs/trifid-api/index.md)
- [dnapi-rs documentation](https://docs.rs/dnapi-rs)
- [dnapi-rs on crates.io](https://crates.io/crates/dnapi-rs)
- [trifid-pki documentation](https://docs.rs/trifid-pki)
- [trifid-pki on crates.io](https://crates.io/crates/trifid-pki)
- [trifid git repository](https://git.e3t.cc/~core/trifid)
- [trifid announcements mailing list](https://lists.e3t.cc/~core/trifid-announce)
- [trifid patch mailing list](https://lists.e3t.cc/~core/trifid-devel)
- [trifid discussion mailing list](https://lists.e3t.cc/~core/trifid-discuss)
# Where does trifid work?
See the [main trifid project page](https://hub.e3t.cc/~core/trifid) for an up-to-date platform support table.
## Why don't mobile devices work?
See the [page on this topic](docs/tfclient/mobile.md).
# Get in touch
Have a question about trifid? Check out the [discussion mailing list](https://lists.e3t.cc/~core/trifid-discuss)! `trifid-discuss` is a mailing list for end-user discussion and questions related to the trifid project.
Run a trifid-api server or otherwise just want to hear news about trifid? Subscribe to our [announcements list](https://lists.e3t.cc/~core/trifid-announce)! `trifid-announce` is a low-volume mailing list for announcements related to the trifid project.
# Contributing
trifid is open source at its heart and we are happy to take your contribution. Send in your patches to the [development mailing list](https://lists.e3t.cc/~core/trifid-devel) and we will get back to you as fast as we can and work on getting your changes merged. Need help sending patches to this list? Check out the handy guide at https://git-send-email.io - or just shoot an email to `trifid-discuss` and we would be happy to help.
# Report a bug
<div class="alert alert-warning">
<strong>Notice</strong>: Do not use this list for security-related issues. Shoot an email to core@e3t.cc if you have a security-related issue and we can have a chat about how to properly report and fix it. We are dedicated to building a secure project, and are glad to work with you to responsibly fix your issue.
</div>
Found a bug in any of the components of trifid? Submit it to [our issue tracker](https://todo.e3t.cc/~core/trifid) to let us know!