Installing carrier

Head over to https://github.com/devguardio/carrier/releases and download the latest binary for your platform. Rename the download locally to just "carrier"
Depending on your OS, copy them to a location within your PATH. This is usually /usr/bin, but you may want to add them to your home directly and instead change your PATH variable. See this stackoverflow thread for instructions.

Creating an identity

Carrier is built on eliptic curve identities, specifically ed25519.
Every device and every user in the system has an identity. We're going to generate yours now.

$ carrier setup
identity: oWDw4B1f88jiGj71qMCYTL8RCCdpRYfgbSNXQSDVByRVHV9

What looks like random numbers, is actually random numbers. This is your identity that was generated out of randomness from your system. The carrier network will know your computer by this id. No registry with any provider is nessesary to create an identity and you may create as many as you want. Unlike an api key, a carrier identity is not tied to a specific service. you may use it in peer to peer communication, or talk to any other service on the carrier network without needing prior registration.

In mass-produced embedded devices, we recommend to generate randomness out of a strong hardware RNG and flash it during production into a read only memory region.

In addition to your identity, a secret is stored in ~/.devguard/carrier.toml . Never share this file with anyone, but do make backups, for example on a hardware security module. If you work in a team or company, /dev/guard also provides hardware security modules as a service with two factor user authentication and group policies.

Putting your thing on the network

Now that we have an identity, we can can expose services on the global bus. carrier does not have user-definable names like domains. There is no central registry, instead everything is cryptographically tied to your identity.

First, let's generate a shadow address, on which we can expose services.

$ carrier mkshadow
address: oTAJ26VtHAEsszr291Bk2dJnNoitCy4ukde9KRP6dLCzc2w
secret:  oNUgmgHGMjy58RBE7EQfjDjF2zPiQrM8ecrY5MWX1gTvNyM

We'll learn what a shadow is later, for now just copy paste the address into the next step as the first argument to axiom.
In order to allow ourselves to login, we also add an additional --accept with the identity we generated earlier.
If you forgot the identity that was generated, run 'carrier identity' to display it.

$ cat ~/.devguard/carrier.toml
secret = "oX..."
[publish]
shadow = "oTAJ26VtHAEsszr291Bk2dJnNoitCy4ukde9KRP6dLCzc2w"
[[authorize]]
identity = "oWDw4B1f88jiGj71qMCYTL8RCCdpRYfgbSNXQSDVByRVHV9"
resource = "*"
$ carrier axon

And we are live! Notice that the broker has an identity too? Currently the broker signature is not checked, but we will add multi level signatures later on.

On a different machine, somewhere in a galaxy far far away,... we can ssh into that thing now only knowing its id. For now we'll just use the same computer.

$ carrier shell oWDw4B1f88jiGj71qMCYTL8RCCdpRYfgbSNXQSDVByRVHV9
INFO 2018-08-09T14:59:24Z: cli: connecting via 34.241.72.31:8443
INFO 2018-08-09T14:59:24Z: cli: via broker oWGPeq8Bvq8XN4wudejQFpddzMvHZr9xb8QWT6WaDc9L53d
INFO 2018-08-09T15:00:24Z: cli: established route to peer oWDw4B1f88jiGj71qMCYTL8RCCdpRYfgbSNXQSDVByRVHV9
Last login: Thu Aug  9 11:27:01 2018 from 192.168.11.239
[aep@box ~ ]

Look ma, no port forwarding! If this seems a little magic to you, let me tell you: it's fricking magic. Well, as magic as basic internet plumbing gets. If you want to know the gritty details, check out the network protocol paper in the github repo.

Http2 like semantics

Because its based on googles QUIC protocol, carrier follows from a high level perspective a similar message flow to http2. That is, every device is actually an rpc server, and a subscriber is an rpc client.

with the axiom still running, we can do:

$ carrier get oWDw4B1f88jiGj71qMCYTL8RCCdpRYfgbSNXQSDVByRVHV9 /v0/system_stats
INFO 2018-09-06T12:00:21Z: carrier: established broker route 0xab6d3d250dad0f6a
INFO 2018-09-06T12:00:21Z: carrier::channel: settled connection with adress 34.241.72.31:8223
INFO 2018-09-06T12:00:21Z: carrier::channel: settled connection with adress 192.168.11.23:52253
[:status = 200, ]
{"timestamp":1536235221,"load":{"load_1":0.33,"load_5":0.31,"load_15":0.2},"mem":{"total":16684097536,
"free":15511363584},"temps":null,"power":{"on_ac_power":false,"remaining_battery_capacity":0.9679004,
"remaining_battery_time":21440},"uptime":15927}

This concludes this short intro. If you have more questions, please feel free to open an issue on github. Happy hacking.