diff --git a/docs/_static/groups/edit.png b/docs/_static/groups/edit.png new file mode 100644 index 0000000..5624a94 Binary files /dev/null and b/docs/_static/groups/edit.png differ diff --git a/docs/_static/groups/list.png b/docs/_static/groups/list.png new file mode 100644 index 0000000..8978cf1 Binary files /dev/null and b/docs/_static/groups/list.png differ diff --git a/docs/_static/groups/new.png b/docs/_static/groups/new.png new file mode 100644 index 0000000..6e960c5 Binary files /dev/null and b/docs/_static/groups/new.png differ diff --git a/docs/_static/ssm/list.png b/docs/_static/ssm/list.png new file mode 100644 index 0000000..b56c5aa Binary files /dev/null and b/docs/_static/ssm/list.png differ diff --git a/docs/_static/ssm/new.png b/docs/_static/ssm/new.png new file mode 100644 index 0000000..f197b31 Binary files /dev/null and b/docs/_static/ssm/new.png differ diff --git a/docs/_static/ssm/shell.png b/docs/_static/ssm/shell.png new file mode 100644 index 0000000..4113c44 Binary files /dev/null and b/docs/_static/ssm/shell.png differ diff --git a/docs/admin/eotk.rst b/docs/admin/eotk.rst new file mode 100644 index 0000000..fe42f13 --- /dev/null +++ b/docs/admin/eotk.rst @@ -0,0 +1,81 @@ +Enterprise Onion Toolkit +======================== + +When EOTK instances are deployed for a group, the following main AWS resources are created: + +* An EC2 instance in us-east-2 +* An EC2 instance in eu-central-1 +* A S3 bucket to hold nginx access logs + +The EC2 instances are running Ubuntu 20.04 LTS and are configured with `ssm-agent `_ +and `unattended-upgrades `_. + +EOTK is automatically cloned at instance creation time from Alec Muffet's +`GitHub repository `_ to ``/home/ubuntu/eotk``. +The script to automatically build and install all dependencies is also executed at the instance creation time. + +For full details on the instance configuration, refer to the +`cloud-init user data `_. + +Logging in to an instance +------------------------- + +Via the console +~~~~~~~~~~~~~~~ + +Using the AWS console, visit the `Session Manager `_ +in the Systems Manager service. +If using SSO, login before attempting to open the link. + +.. image:: /_static/ssm/list.png + :width: 800 + +Click "Start Session" to start a new session. + +.. image:: /_static/ssm/new.png + :width: 800 + +Select the instance from the list, and click "Start Session" again. +Remember that the second instance will be found in the eu-central-1 region. + +.. image:: /_static/ssm/shell.png + :width: 800 + +Use the following commands to get into the EOTK directory as the correct user:: + + sudo -u ubuntu bash + cd /home/ubuntu/eotk + +Via the command line +~~~~~~~~~~~~~~~~~~~~ + +Begin by discovering the instance ID:: + + AWS_REGION=us-east-2 aws ec2 describe-instances + +Start an SSM session:: + + AWS_REGION=us-east-2 aws ssm start-session --target i-083da3fcf840c4797 + +To login with SSH via SSM, add the following to your ``~/.ssh/config``: + +.. note:: + + No user SSH public keys are provisioned to the instance. You will need to add the public key you plan to use to the + correct user's authorized_keys file using a plain SSM session before attempting to use SSH. + +.. code-block:: + + Host i-* mi-* + ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'" + +You can then login with SSH, but be sure to include environment variables for your AWS region:: + + AWS_REGION=us-east-2 ssh ubuntu@i-083da3fcf840c4797 + +This will also work for scp, rsync, etc. + +Configuring EOTK +---------------- + +Refer to the `EOTK documentation `_. \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 0775650..0804db2 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -12,6 +12,7 @@ Documentation Home user/index.rst user/proxies.rst + user/eotk.rst user/bridges.rst user/lists.rst @@ -21,6 +22,7 @@ Documentation Home admin/index.rst admin/conf.rst + admin/eotk.rst .. toctree:: :maxdepth: 2 diff --git a/docs/user/eotk.rst b/docs/user/eotk.rst new file mode 100644 index 0000000..cb9eccd --- /dev/null +++ b/docs/user/eotk.rst @@ -0,0 +1,60 @@ +Enterprise Onion Toolkit +======================== + +Once your administrator has provided you access to the portal, you can begin to configure your onion service +deployments. To get started, select "Groups" under "Configuration" from the menu on the left hand side. +If you are using a mobile device, you may need to click the hamburger icon at the top of the screen to open the menu. + +.. image:: /_static/groups/list.png + :width: 800 + +You will see a ✅ or ❌ in the "EOTK" column for the group to show whether or not EOTK instances are enabled for that +group. + +Creating a new group +-------------------- + +If the group you would like to use EOTK for does not yet exist, create a new group by clicking the "Create new group" +button. + +.. image:: /_static/groups/new.png + :width: 800 + +Short Name +"""""""""" + +This must be a unique short name for the group. It needs to be short. No more than 4-5 characters. + +Description +""""""""""" + +A free-form description for the group. + +Deploy EOTK instances +""""""""""""""""""""" + +Tick this checkbox to deploy EOTK instances for this group. + +Adding EOTK to an existing group +-------------------------------- + +Click "View/Edit" next to the group that you'd like to edit. + +.. image:: /_static/groups/edit.png + :width: 800 + +Description +""""""""""" + +A free-form description for the group. + +Deploy EOTK instances +""""""""""""""""""""" + +Tick this checkbox to deploy EOTK instances for this group. + +Managing EOTK instances +----------------------- + +It is not currently possible to manage the EOTK instances via the portal. Rather, you must use the AWS Systems Manager +to manage the EOTK instances via the command line. See the :doc:`Administration Guide <../admin/eotk>` for more details. \ No newline at end of file