d9727d5c6405ae92f5321dab1cb7ea24ce5daabf — Joris 'Tifox' BOQUET 12 days ago 2e180d9 master
add documentation about csc usage in the README
1 files changed, 310 insertions(+), 0 deletions(-)

M README.md
M README.md => README.md +310 -0
@@ 1,3 1,4 @@+  # cisco
  
  ![XKCD - The Cloud](https://imgs.xkcd.com/comics/the_cloud.png)


@@ 58,6 59,315 @@ ### api
  ### csc
  
+ `csc` is the command-line tool used for sending orders to the cluster by your
+ endpoint.  This is some examples of this command, like default configuration
+ files and how to manage your instances.
+ 
+ #### **Config File**
+ 
+ you can find it at `~/.config/csc/config.yml`
+ 
+     debug: false
+     endpoint: https://api.louifox.house
+     key: 
+     secret: 
+ 
+ `endpoint`: Your endpoint URL, it is given to you by your cluster's admin
+ 
+ - `key` : A unique ID, it's your token, it is print to you when you generate a
+   token, don't loose it
+ - `secret` : your secret exchange key, couple with you key to identify you,
+   same as the `key`, it is print to you when you generate a token, don't lost
+   it too.
+ 
+ #### Invitation
+ 
+ **Claiming an invitation**
+ 
+ You can find the link and command in the invitation mail sent to you by your cluster's admin
+ 
+ The API gonna ask you your Username and a Password, **don't forget them**
+ 
+ example:
+ 
+     -> % csc invite claim d04b98f48e8f8bcc15c6ae5ac050801cd6dcfd428fb5f9e65c4e16e7807340fa --endpoint https://api.louifox.house
+     Choose an username: example
+     Enter a password:
+     Please confirm password:
+ 
+     Account created, getting your credentials for the configuration...
+     All done! You can now query the service. You should take a look at 'csc help' for more information
+ 
+ **Send an invite**
+ 
+ You can invite someone to join the cluster, be cool, ask your cluster admin before.
+ 
+ Use the command: `csc invite new`
+ 
+ Example:
+ 
+     -> % csc invite new example@louifox.house
+     Done! User should have received an invite mail
+ 
+ 
+ The cluster endpoint is gonna send the same mail that you received.
+ 
+ #### **Manipulating Tokens**
+ 
+ Token is the key of **cisco**, we recommend you to create a unique token by
+ machine, in case one of your machine is compromised, you can just revoke
+ the associated token. First thing we recommend after claiming your
+ invite is the creation of your first token.
+ 
+ **List your tokens**
+ 
+ You can list your tokens with: `csc token list`
+ 
+ Example:
+ 
+     -> % csc token list
+     +--------------------------------------+--------------------------------+------------------------------+
+     |                 KEY                  |          DESCRIPTION           |          CREATED AT          |
+     +--------------------------------------+--------------------------------+------------------------------+
+     | ba21f1ee-9043-8632-dd32-2cf6f52083de | Default keys (Created by the   | Fri Feb  7 13:23:57 UTC 2020 |
+     |                                      | command line tool)             |                              |
+     +--------------------------------------+--------------------------------+------------------------------+
+ 
+ As you can see, when you claim your invite, `csc` just fill your config file
+ with an initial default token.
+ 
+ **Create a Token**
+ To create a token, use the command
+ 
+ `csc token new`
+ 
+ It will ask your Username and Password and give to you a Key and Secret to refer in your config file.
+ 
+ Example:
+ 
+     -> % csc token new
+     Username: example
+     Password:
+     Description (can be empty): MyMainLaptop
+     ===== TOKEN =====
+     key: 64a73aca-6da0-32cf-9734-5ebdaa2bcef9
+     secret: XXXXXX
+     This is the only time you will see this secret. Do not loose it!
+ 
+ Uou can now verify that you have 2 token with a `csc token list`
+ 
+ **Don't forget to update your config file with this value to use this token.**
+ 
+ **Revoke a Token**
+ 
+ Simply execute :
+ 
+ `csc token revoke <key>`
+ 
+ Verify it is now removed with a `csc token list`
+ 
+ ## Managing SSH Keys
+ 
+ **List your SSH Keys**
+ Use the command : `csc ssh list`
+ 
+ List your actual loaded keys, notice that all your keys in this list will
+ be added to the `authorized_keys` when you create / reboot an instance.
+ 
+ Example :
+ 
+     -> % csc ssh list
+     +-------------+------------+
+     | FINGERPRINT | CREATED AT |
+     +-------------+------------+
+     +-------------+------------+
+ 
+ **Adding a SSH Key**
+ Use the command : `csc ssh add <MyKey.pub>`
+ 
+ Example :
+ 
+     -> % csc ssh add .ssh/MySSHKey@MyMainLaptop.pub
+ 
+ Verify that the key is present with a `csc ssh list`
+ 
+ Example of a correct add:
+ 
+     -> % csc ssh list
+     +-------------------------------------------------+------------------------------+
+     |                   FINGERPRINT                   |          CREATED AT          |
+     +-------------------------------------------------+------------------------------+
+     | e3:de:b1:a2:32:8f:ce:10:41:2a:05:c7:42:42:42:42 | Fri Feb  7 13:55:26 UTC 2020 |
+     +-------------------------------------------------+------------------------------+
+ 
+ **Delete a SSH Key**
+ Use the command : `csc ssh delete <FINGERPRINT>`
+ 
+ Example :
+ 
+     -> % csc ssh delete e3:de:b1:a2:32:8f:ce:10:41:2a:05:c7:42:42:42:42
+ 
+ Verify it is not present on the list with a `csc ssh list`
+ 
+ ## Managing Instance
+ 
+ **List your instances**
+ Use the command : `csc instance list`
+ 
+ Example :
+ 
+     -> % csc instance list
+     +------+--------+------+----+------+------+
+     | NAME | STATUS | TYPE | OS | IPV6 | SIZE |
+     +------+--------+------+----+------+------+
+     +------+--------+------+----+------+------+
+ 
+ **Creating an Instance**
+ To create an instance, you will need 4 things:
+ 
+  1. a Name
+  2. an OS
+  3. a Type
+  4. a Size (disk)
+ 
+ Please be explicit and cautious with your instance's name.
+ To choose an OS, refer to [csc:image-list](https://git.mobley.ne02ptzero.me/~louis/cisco/tree/refs/heads/master/#image)
+ For the Type, refer to [csc:instance-type](https://git.mobley.ne02ptzero.me/~louis/cisco/tree/refs/heads/master/#instance-type)
+ For the Size, check your quota ([csc:quota](https://git.mobley.ne02ptzero.me/~louis/cisco/tree/refs/heads/master/#quota)) if your need more quota, ask to your cluster's admin
+ 
+ Example of creation:
+ 
+     -> % csc instance new tototest-mybouncer debian/buster I-0 --size 30
+ 
+ This will create an instance with this specification :
+ 
+  1. Name : tototest-mybouncer
+  2. OS : Debian Buster
+  3. Type : I-0 [csc:instance-type](https://git.mobley.ne02ptzero.me/~louis/cisco/tree/refs/heads/master/#instance-type)
+  4. Size : 30GB
+ Verify the correct creation with a `csc instance list`
+ 
+ Example:
+ 
+     -> % csc instance list
+     +--------------------+---------+------+---------------+------+------+
+     |        NAME        | STATUS  | TYPE |      OS       | IPV6 | SIZE |
+     +--------------------+---------+------+---------------+------+------+
+     | tototest-mybouncer | Stopped | I-0  | debian/buster |      | 30GB |
+     +--------------------+---------+------+---------------+------+------+
+ 
+ **Start an Instance**
+ Use the command : `csc instance start <NAME>`
+ Example:
+ 
+     -> % csc instance start tototest-mybouncer
+ 
+ You can now see you instance is on running status and have an IPv6 address with a `csc instance list`
+ Example: 
+ 
+     -> % csc instance list
+     +--------------------+---------+------+---------------+------------------------------------+------+
+     |        NAME        | STATUS  | TYPE |      OS       |                IPV6                | SIZE |
+     +--------------------+---------+------+---------------+------------------------------------+------+
+     | tototest-mybouncer | Running | I-0  | debian/buster | 2001:470:c85d:32:216:3eff:fe7f:33d | 30GB |
+     +--------------------+---------+------+---------------+------------------------------------+------+
+ 
+ **Connecting to your instance**
+ Just a classic `ssh root@<IPv6>` please be sure you have your key loaded in your ssh-agent.
+ 
+ **Stop an instance**
+ Use the command : `csc instance stop <NAME>`
+ Example:
+ 
+     -> % csc instance stop tototest-mybouncer
+ 
+ Verify its state with a `csc instance list`
+ 
+ **Delete an instance**
+ Use command : `csc instance delete <NAME>`
+ Example:
+ 
+     -> % csc instance delete tototest-mybouncer
+ 
+ Verify the instance had been delete with a `csc instance list`
+ 
+ **Be careful, this is permanent**
+ 
+ **Renaming an instance**
+ Use the command : csc instance set name <NAME> <NEW_NAME>
+ Example:
+ 
+     -> % csc instance set name tototest-mybouncer tototest-mybouncer-renamed
+ 
+ Verify the new name with a `csc instance list`
+ 
+ **Change the Type of an instance**
+ You can **Hot-Change** the type of an instance, if you need more RAM of CPU
+ Use the command : `csc instance set type <NAME> <NEW_TYPE>`
+ Example:
+ 
+     -> % csc instance set type tototest-mybouncer I-2
+ 
+ Verify with a `csc instance list`
+ 
+ **Refer to [csc:instance-type](https://git.mobley.ne02ptzero.me/~louis/cisco/tree/refs/heads/master/#instance-type) for all types.**
+ 
+ **Resize an instance**
+ 
+ Use the command : `csc instance set size <NAME> <NEW_SIZE>`
+ Example:
+ 
+     -> % csc instance set size tototest-mybouncer 50
+ 
+ Done! **You need to restart the instance in order to use the new disk space**.
+ Verify it with a `csc instance list`
+ 
+ **Tricks Command**
+ 
+ There is two command who are compact utilization, when your are comfortable with `csc` you can using it.
+ 
+ They are : `csc instance launch`
+ Description : it combine a `csc instance new` and a `csc instance start`, it creates **AND** start a newly instance
+ Example: 
+ 
+     -> % csc instance launch tototest-mybouncer debian/buster I-0 --size 30
+ 
+ The other one is `csc instance destroy` be careful with it, its a `csc instance
+ stop` and `csc instance delete`, so you will **delete** your instance.
+ Example:
+ 
+     -> % csc instance destroy tototest-mybouncer
+ 
+ #### Instance Types
+ This is an actual list of all type of instance, you can find it with `csc instance types`
+ 
+     +------+--------------+-----+---------+-----------+
+     | NAME | ARCHITECTURE | CPU | MEMORY  |   TYPE    |
+     +------+--------------+-----+---------+-----------+
+     | I-0  | x86_64       |   1 | 256MB   | container |
+     | I-1  | x86_64       |   2 | 2048MB  | container |
+     | I-2  | x86_64       |   4 | 8192MB  | container |
+     | I-3  | x86_64       |   8 | 16384MB | container |
+     | I-4  | x86_64       |  16 | 32768MB | container |
+     | A-0  | arm          |   1 | 256MB   | container |
+     | A-1  | arm          |   2 | 1024MB  | container |
+     +------+--------------+-----+---------+-----------+
+ 
+ #### Image/OS List
+ This is the actual list of all Image / OS available, you can find it with `csc image list`
+ 
+     +-------------------+--------------+
+     |       NAME        | ARCHITECTURE |
+     +-------------------+--------------+
+     | debian/stretch    | x86_64       |
+     | archlinux/current | x86_64       |
+     | debian/buster     | x86_64       |
+     | archlinux/current | armv7l       |
+     | debian/buster     | armv7l       |
+     +-------------------+--------------+
+ 
+ Don't panic, `csc` will **autodetect the architecture**, its depend on your instance's type
+ 
  ## Contributing
  
  If you want to contribute, please send your patches to