Splitops improved Readme file

1 files changed, 115 insertions, 27 deletions

diff --git a/splitops/README.md b/splitops/README.md
index a349ce3..25ecaaf 100644
--- a/splitops/README.md
+++ b/splitops/README.md
@@ -1,40 +1,128 @@
-# splitops
+# Splitops
+================
 
 Splitops is a script to allow execution of commands only after the approval of
-multiple users.
+multiple users. 
 
 It is intended to be used with OpenSSH by specifiying it as the "command" option
-for authorized users in `~/.ssh/authorized_keys`.
+for authorized users in `~/.ssh/authorized_keys` (explained below).
 
-For example, consider following `authorized_keys` file for the user `root`:
+Server requirements:
+=====================
 
-```
-command="/bin/splitops --user=alice" [... key of alice ...]
-command="/bin/splitops --user=bob" [... key of bob ...]
-```
+GNU/linux server.
+The Splitops program is written in the Python programming language, so you will need to have installed the 
+python3 package in your server, please check in your terminal by typing "python3 -V", to see if you have this package already installed. 
 
-This allows Alice and Bob to jointly run commands:
+Please do before using the program
+=====================================
 
-```
-bob$ ssh root@server propose rm -rf /opt/something
-authenticated as: bob
-requested command: ['rm', '-rf', '/opt/something']
-assigned id: ccafbd
+1) From your local computer git clone the deployment.git repository, and within the "splitops" folder, 
+copy the file "splitops" from your computer to the remote server (path:/usr/local/bin/). There is no need for you
+to clone the whole deployment.git repository from the remote server to grab this program.  
 
-bob$ ssh root@server approve ccafbd
+You can use the command "scp" for this. 
 
-alice$ ssh root@server get 
-{'cmd': ['rm', '-rf', '/opt/something'], 'request_id': 'ccafbd'}
+scp /home/user/deployment/splitops/splitops root@server:/usr/local/bin/
 
+2) In your remote server SSH configuration (/etc/ssh/sshd_config), 
+please make sure you have the option "PubkeyAuthentication yes" is 
+de-commented. If not, decomment the line, and --reload your ssh service. 
 
-alice$ ssh root@server approve ccafbd
+3) In your /root/.ssh/authorized_keys, please add the next lines:
 
-bob$ ssh root@server run ccafbd
-==stdout==
-...
-====
-==stderr==
-...
-====
-exit status: 0
-```
+command="/usr/local/bin/splitops alice" [... key of alice ...]
+command="/usr/local/bin/splitops bob" [... key of bob ...]
+
+(one for each user, that you want to have approval from for each command request)
+
+"Alice" and "Bob" are just usernames, they don't need to be real user system accounts in the remote server. 
+
+The way the splitops program works, is by associating a public SSH key to a username, but this username doesn't need to match, 
+with the real username you are using for a specific SSH public key. 
+
+Having these 2 lines in the .ssh/authorized_key files, will *force* --anyone trying to login in as root through SSH, 
+to execute the program: "splitops", so any other user not listed in this root/.ssh/authorized_key file, won't be able to do anything. 
+
+4) Logout from the remote server, and from your client machine, in order to start using the program Splitops, 
+try to "request" your very first command. This is done by using the splitops sub-command "propose". 
+
+e.g: ssh root@server propose rm -rf /opt/something
+
+After executing this, you will have some sort of answer from the server such as next:
+
+- authenticated as: bob
+- requested command: ['rm', '-rf', '/opt/something']
+- assigned id: ccafbd
+
+That means, your new command request, is waiting for approval. 
+
+Now, you (if you are either Alice or Bob), you can "approve" this command request, and afterwards wait for
+others to do the same thing (until the approval is complete for the number of users listed on the .ssh/authorized keys of the remote server).  
+
+Let's say you are Bob for now,
+---------------------------------
+
+bob@computer:~$ root@server get # To see if you have anything pending to approve
+
+And you will see a list of pending requests. Now get the the ID of any request you want to approve, 
+let's say "ccafbd", then type:
+
+bob@computer:~$ root@server approve ccafbd
+
+Now you have to ask Alice, to approve the same request "ccafbd"
+
+Alice will do,
+
+alice@computer:~$ root@server approve ccafbd
+
+And finally you will be able to --remotely execute "as root", that specific and --approved command:
+
+bob@computer:~$ ssh root@server run ccafbd
+
+Summary
+========
+
+Once the production remote server is up an running using the "splitops" command, a routine for you as "double-check systems administrator"
+would be to use the next splitops sub-commands (get, propose,approve, discargd, run...)
+
+alice@computer:~$ root@server get # To see if you any pending commands to approve
+alice@computer:~$ root@server approve "some ID" # To approve a specific command
+alice@computer:~$ root@server run "some ID" # To run, a specific approved command
+alice@computer:~$ root@server propose cp /opt/something /usr/local/something # (and wait)
+
+e.g 1) IF you try to "run" a command, but you don't have enough approvals, you will receive some output as this:
+
+- authenticated as: --user=javier
+- running command with ID bcb6a5
+- not enough approvals, got 1 but need 2
+
+e.g 2) If you try to connect to the remote server as --root, and without using any Splitops sub-command, you will receive the 
+next answer from the server:
+
+alice@computer:~$ ssh root@server
+- authenticated as: --user=alice
+- no command provided, try help
+- Connection to 78.141.227.64 closed.
+
+
+Full command list
+===================
+CMDID= The hash assigned to each command request. 
+
+whoami: Check authentication
+propose CMD ...: Propose a new command
+get: Get the currently proposed command
+approve CMDID: Approve a command
+run CMDID: Run a sufficiently approved command
+discard: Discard the currently proposed command
+
+Please remember you have to use this sub-command remotely from your computer, towards the remote server, by using the "root" user. 
+Or with the user of your choice, who has on its .ssh/authorized_key file, the users list, with the OpenSSH "command= ..." option.
+
+[*]- Also take into account, if any other user "propose" a new command, the last "proposed" command will be discarded. The program doesn't use a stack 
+to store all requests, it works just with 1 single request. So even if you have been approved by several users, a specific CMDID, you won't be able 
+to run it, if a new command --proposal has been requested.
+
+[*] We encourage all users interested in using the Splitops command to user it first with --normal user, and not the root user. So this way you
+can learn how the program behaves without losing the connection with your server for the root user.