Merge pull request #107 from skalenetwork/enhancement/update-documentation

Update documentation

Merge pull request #107 from skalenetwork/enhancement/update-documentation
Update documentation
3b1b145b · Chadwick Strange · GitHub · df8ce3b6 · 4137999f · 3b1b145b
Unverified Commit 3b1b145b authored 4 years ago by Chadwick Strange Committed by GitHub 4 years ago
10 changed files
--- a/docs/README.md
+++ b/docs/README.md
+# SGXWallet Documentation
+
+-   [Admin Guide](admin-guide.md)
+-   [Developer Guide](developer-guide.md)
--- a/docs/admin_guide.md
+++ b/docs/admin_guide.md
@@ -4,7 +4,12 @@

 -   [Verify that your hardware and software can run SGX](prerequisites.md)
 -   [Enable SGX](enabling-sgx.md)
-   [Start, stop and upgrade sgxwallet](run_in_hardware_mode.md)
+-   [Start, stop and upgrade sgxwallet](run-in-hardware-mode.md)
+    -   [Docker Compose configuration](run-in-hardware-mode.md#docker-compose-configuration)
+    -   [Run sgxwallet in secure mode](run-in-hardware-mode.md#run-sgxwallet-in-secure-mode)
+    -   [Start, stop and upgrade sgxwallet containers](run-in-hardware-mode.md#start-stop-and-upgrade-sgxwallet-containers)
+    -   [Logging](run-in-hardware-mode.md#logging)
+-   [Backup and recover sgxwallet](backup-procedure.md)

 ## Community


--- a/docs/backup-procedure.md
+++ b/docs/backup-procedure.md
+<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
+
+# SGXWallet Backup Procedure
+
+When SGXWallet is initialized, the server will print the backup key. 
+**This key must be securely recorded and stored.**
+
+Master-Slave replication is recommended to support the SGXWallet backup strategy. Below are general instructions for a basic backup and recovery process.
+
+## Backup SGXWallet (manual copy)
+
+1.  Stop the container:
+
+```bash
+docker-compose down
+```
+
+2.  Copy the entire `sgx_data` directory.
+
+## Recover from backup
+
+1.  Edit the `docker-compose.yml` and add the `-b` flag to recover from backup.
+
+```yaml
+command: -s -y -d -b
+```
+
+2.  Edit the `docker-compose.yml` and add `stdin_open: true` option. For example:
+
+```yaml
+version: "3"
+services:
+  sgxwallet:
+    image: skalenetwork/sgxwallet:latest
+    stdin_open: true
+```
+
+3.  Copy the backed up `sgx_data` directory to the recovery `sgx_data` directory.
+4.  Execute:
+
+```bash
+docker-compose up -d
+```
+
+5.  Open another terminal window and run `docker attach container_name` there.
+
+6.  Enter the backup key when prompted.
+7.  Edit the `docker-compose.yml` file, remove the `-b` flag and `stdin_open: true` option.
--- a/docs/building.md
+++ b/docs/building.md
-# Building SGX wallet from source
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->

+# Building SGX wallet from source
+
 ## Clone this repository and its submodules

 `git clone --recurse-submodules  https://github.com/skalenetwork/sgxwallet.git`

--- a/docs/developer_guide.md
+++ b/docs/developer_guide.md
--- a/docs/enabling-sgx.md
+++ b/docs/enabling-sgx.md
-# Enabling SGX
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->

-### Verify Intel SGX is enabled in BIOS
+# Enabling SGX
+
+## Verify Intel SGX is enabled in BIOS

 Enter BIOS by pressing the BIOS key during boot.
 The BIOS key varies by manufacturer and could be F10, F2, F12, F1, DEL, or ESC.
@@ -26,7 +26,7 @@ This repo includes the **_sgx_enable_** utility. To enable SGX run:
 sudo ./sgx_enable
 ```

-Note: if you are not using Ubuntu 18.04 (something that we do not recommend), you may need
+Note: if you are not using Ubuntu 18.04 (Not recommended!), you may need
 to rebuild the sgx-software-enable utility before use by typing:

 ```bash
@@ -36,7 +36,7 @@ make

 ## Install SGX driver

-Install make and gcc if you do not have it
+Install make and gcc if you do not have it:

 ```bash
 apt-get install  build-essential
@@ -48,8 +48,8 @@ Run the following command:
 cd scripts; sudo ./sgx_linux_x64_driver_2.5.0_2605efa.bin; cd ..
 ```

-You can also try other driver versions from Intel website, but version 2.5.0_2605efa is what
-that we use in testing.
+Alternatively, other driver versions may be downloaded from Intel.
+Please note that version `2.5.0_2605efa` is what is currently supported.

 Reboot you machine after driver install.  Do `ls /dev/isgx` to check that `isgx` device is properly installed.
 If you do not see the `isgx` device, you need to troubleshoot your driver installation.
@@ -63,16 +63,16 @@ git clone https://github.com/intel/linux-sgx-driver

 And then follow instructions in README.md

-# Troubleshooting Installation
+## Troubleshooting Installation

 -   If the message  `intel_sgx: SGX is not enabled` appears in `/var/log/syslog`
-    Intel SGX needs to be enabled in BIOS
+    Intel SGX needs to be enabled in BIOS.

 -   If you are running in Intel SGX hardware mode, make sure you have device
    `/dev/isgx` (and not `/dev/sgx`). Review the Intel SGX device driver
    installation instructions above. If you have `/dev/sgx` the
-    device driver must be removed first
+    device driver must be removed first.

 -   If you are running in Intel SGX hardware mode, you need to modify
    the `ias_api_key` in `config/tcs_config.toml` with your
-    IAS Subscription key obtained in the instructions above
+    IAS Subscription key obtained in the instructions above.
--- a/docs/examples.md
+++ b/docs/examples.md
-# Example usage
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->

+# Example usage
+
 ## Run sgxwallet from build

 Type:
@@ -59,7 +59,7 @@ curl -X POST --data '{ "jsonrpc": "2.0", "id": 2, "method": "signCertificate", "

 The above example produces on success:

-```
+```json
 {"id":2,"jsonrpc":"2.0","result":{"errorMessage":"","result":true,"status":0}}

 ```
@@ -91,7 +91,7 @@ curl \

 The above example produces on success:

-```
+```json
 {"id":1,"jsonrpc":"2.0","result":{"encryptedKeyShare":"0400020000000000040effffff02000000000000000000000b000000000000ff0000000000000000cecb5d7bd507cb936464fdb6b88cfe80e38eae963af6a39b6b05cdfba5521c60000000f0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000008000000000000000000000000000000080000000000000000000000000000000875c0520e8d6739c440e0e5073633861769fc1d31d627e9a72c66d43871c62bce2cc48e821341e10784242c4c8aad6ca73a491cbf7453c2ff012b6b3d9d96823c0256992d9792ea60269789b2d51ae87c75fe522dbcb8053458c1bca421cbc57f4a58e4e5689d534ca0303db83c7a9e88cd23afe3a39e1a3801371c95e7ffa54e834c6be8853983dcaa1fa9f5e6959a5","errorMessage":"","status":0}}

 ```
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
-# SKALE sgxwallet Prerequisites
-
 <!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->

+# SKALE sgxwallet Prerequisites
+
 sgxwallet depends on several freely available
 software components. These must be installed and configured before
 running sgxwallet.
@@ -9,7 +9,7 @@ This document describes how to install and configure these required components.

 ## Recommended host system

-sgxwallet should be ran on Ubuntu 18.04. Sgxwallet has been tested on Ubuntu 18.04.
+sgxwallet has been tested and should be run on Ubuntu 18.04.

 Sgxwallet may run on other Linux distributions, 
 but the installation process is likely to be more complicated, 
@@ -50,4 +50,4 @@ Verify processor support of Intel SGX:
 cpuid | grep SGX:
 ```

-The printout should read  `SGX: Software Guard Extensions supported = true`
+The printout should read: `SGX: Software Guard Extensions supported = true`
--- a/docs/run-in-hardware-mode.md
+++ b/docs/run-in-hardware-mode.md
+<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
+
+# Run in hardware secure mode
+
+-   [Docker Compose configuration](#docker-compose-configuration)
+-   [Run sgxwallet in secure mode](#run-sgxwallet-in-secure-mode)
+-   [Start, stop and upgrade sgxwallet containers](#start-stop-and-upgrade-sgxwallet-containers)
+-   [Logging](#logging)
+
+## Docker Compose configuration
+
+Install docker-compose:
+
+```bash
+sudo apt-get install docker.io docker-compose
+```
+
+Edit `docker-compose.yml` as needed with the appropriate devices, ports, command flags, and healthcheck.
+
+### Devices
+
+Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such 
+as `/dev/bs0`. In this case please edit  `docker-compose.yml` to specify the correct 
+device to use. 
+
+### Ports
+
+sgxwallet operates on the following network ports:
+
+-   1026 (https)
+-   1027 (http for initial SSL certification signing)
+-   1028 (localhost for admin )
+-   1029 (http only operation)
+
+If operating with a firewall, please make sure these ports are open so clients are able to connect to the server. 
+
+### Command Flags
+
+-   \-h     Display available flags
+-   \-c     Do not verify client certificate
+-   \-s     Sign client certificate without human confirmation
+-   \-d     Turn on debug output
+-   \-v     Verbose mode: turn on debug output
+-   \-vv    Detailed verbose mode: turn on debug and trace outputs
+-   \-n     Launch SGXWalletServer using http (not https)
+-   \-b     Restore from back up (you will need to enter backup key) 
+-   \-y     Do not ask user to acknowledge receipt of backup key 
+-   \-T     Generate test keys     
+
+### Healthcheck
+
+Healthcheck devices should match the same devices specified under `devices`.
+
+Note: All docker-compose commands herein need to be issued from `run_sgx` directory. If running in simulation mode, use `run_sgx_sim`.
+
+Note: sgxwallet places all its data into the `sgx_data` directory, which is created when sgxwallet is initialized.
+**This directory must be backed up. Do not remove this directory!**
+
+## Run sgxwallet in secure mode
+
+```bash
+cd run_sgx; sudo docker-compose up -d
+```
+
+The server should display: "SGX Server started".
+
+If not, confirm that the SGX device drivers are correctly configured to the machine.
+
+## Start, stop and upgrade sgxwallet containers
+
+To run the server as a daemon, do
+
+```bash
+sudo docker-compose up -d
+```
+
+To stop/start the server do 
+
+```bash
+sudo docker-compose stop
+sudo docker-compose start
+```
+
+To view server logs do 
+
+```bash
+sudo docker-compose logs
+```
+
+To upgrade sgxwallet to a different version:
+
+1.  First stop the container:
+
+```bash
+sudo docker-compose stop
+```
+
+2.  Edit `docker-compose.yml` with the appropriate container tag:
+
+```yaml
+image: skalenetwork/sgxwallet:<TAG>
+```
+
+3.  Pull and start the container:
+
+```bash
+sudo docker-compose pull
+sudo docker-compose up
+```
+
+## Logging
+
+By default, sgxwallet will log into default Docker logs, which are rotated into four files 10M each.
+To send logs to an external syslog service, edit docker compose YAML file to specify logging configuration as 
+
+```yaml
+logging:
+  driver: syslog
+  options:
+    syslog-address: "tcp://SYSLOG_SERVER_IP:PORT"
+
+```
+
+See docker-compose documentation for more options.
--- a/docs/run_in_hardware_mode.md
+++ b/docs/run_in_hardware_mode.md
-# Configuring sgxwallet server in hardware secure mode
-
-<!-- SPDX-License-Identifier: (AGPL-3.0-only OR CC-BY-4.0) -->
-
-## Docker Compose configuration
-
-Install docker-compose if you do not have it.
-
-```bash
-sudo apt-get install docker.io docker-compose
-```
-
-## Run sgxwallet in secure mode
-
-```bash
-cd run_sgx; sudo docker-compose up -d
-```
-
-You should see "SGX Server started" message.
-
-Note: on some machines, the SGX device is not `/dev/mei0` but a different device, such 
-as "/dev/bs0". In this case please edit  `docker-compose.yml` on your machine to specify the correct 
-device to use. 
-
-## Start, stop and upgrade sgxwallet containers
-
-As any docker-compose application sgxwallet is super easy to use. 
-
-To run the server as a daemon, do
-
-    sudo docker-compose up -d
-
-To stop/start the server do 
-
-    sudo docker-compose stop
-    sudo docker-compose start
-
-To view server logs do 
-
-    sudo docker-compose logs
-
-To upgrade sgxwallet to the latest version do 
-
-    sudo docker-compose stop
-    sudo docker-compose pull
-    sudo docker-compose up
-
-Note: all docker-compose commands need to be issued from run_sgx_sim directory.
-
-Note: sgxwallet places all its data into the sgx_data directory, which is created the first time you run sgxwallet.
-Do not remove this directory!
-
-Note: sgxwallet operates on network ports 1026 (https) and 1027 (http for initial registration). 
-If you have a firewall on your network, please make sure these ports are open so clients are able to
-connect to the server. 
-
-## Logging
-
-By default, sgxwallet will log into default Docker logs, which are rotated into four files 10M each.
-To send logs to an external syslog service, edit docker compose YAML file to specify logging configuration as 
-
-```yaml
-logging:
-  driver: syslog
-  options:
-    syslog-address: "tcp://SYSLOG_SERVER_IP:PORT"
-
-```
-
-See docker-compose documentation for more options.