trusted-sandbox 0.0.9.pre → 0.0.10.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e96be24e19e847b10942e3e8c72493f8b5cb0ce9
-  data.tar.gz: df3f3cccad8434b8752ee146db68fa33dd78882c
+  metadata.gz: 087e7a3db62be30fbceb951541f60d39185fd272
+  data.tar.gz: 470126d53f50f5f75a8a6210c6205169ad3102fa
 SHA512:
-  metadata.gz: a5165ce3e2d8ad14bf2bdb8609cc2dd87c203d7d5231c6a09aa8811b8f41748b70c7378a5c88fd3cf52bbad2d8866ee0152d99c38bcd9bd14ded6e45d4cc523f
-  data.tar.gz: e9f975e0d6c180566ccdf66596b593176980cdb34f5ad57457ba9c685e3c37d1070af0a659d8408be53a1b5918d75f55a4c84a1b1c55d6d83d0ee715350aa567
+  metadata.gz: 1acd7ef23ac33477479793c38ae674cd62284e8e60e1f186ed2cd375c5bcccd2482861ab3c948fbad9454f8905cb9b9c9fe4a18b27ec30ffca5f04194f4d3546
+  data.tar.gz: fac057c808f1bf3da35f30432b4125783099358bca06b196bcfbd88edd0f29b96fbb33f7d9552af3739b71551595ab6f24bbdc87c773b04ddccf888e59d15ac8

data/README.md

@@ -54,17 +54,17 @@ $ gem install trusted-sandbox
 ```
 
 ### Step 2
-Install the latest version of Docker. **Do not** install from your distro pacakge management system, as the docker
-version is old and does not support what Trusted Sandbox needs. Refer to the Docker documentation to see how to install
-Docker on your environment.
+Install Docker, Server version >= 1.2.0. Note that at the time of writing some distro package management systems have
+an earlier version. Refer to the Docker documentation to see how to install the latest Docker on your environment.
 
-Note that on a Linux server the docker daemon runs as root and owns the socket used to connect to it.
-To give your app user access to that socket you will need to add the user to the docker group.
+Note that on a Linux server the docker daemon runs as root, and the root user owns the socket used to connect to the
+daemon. In order to avoid the need to run your application with sudo privileges, add the application user to the
+`docker` group (keep `${USER}` for the connected user or change to suit your needs):
 ```
 $ sudo gpasswd -a ${USER} docker
 $ sudo service docker.io restart
 ```
-then reconnect to your shell session and try the following (without sudo command):
+then reconnect to your shell session and try the following (without sudo):
 ```
 $ docker images
 ```
@@ -79,7 +79,8 @@ Run the following command which will copy the `trusted_sandbox.yml` file into yo
 $ trusted_sandbox install
 ```
 
-Then follow the configuration instructions below. Once you're done configuring, test your installation by running:
+Then follow the configuration instructions in this guide. Once you're done configuring, test your installation by
+running:
 ```
 $ trusted_sandbox test
 ```
@@ -92,8 +93,10 @@ $ docker run --rm vaharoni/trusted_sandbox:2.1.2.v1
 ```
 If you see the message "you must provide a uid", then you are set.
 
-If you receive an error that looks like this: `Error response from daemon: Cannot start container 9f3bd8d72f0704980cedacc068261c38e280e7314916245550a6d48431ea8f11: fork/exec /var/lib/docker/init/dockerinit-1.0.1: cannot allocate memory`
-consider restarting docker:
+Consider restarting the docker service if you receive an error that looks like this:
+`Error response from daemon: Cannot start container 9f3bd8d72f0704980cedacc068261c38e280e7314916245550a6d48431ea8f11:
+fork/exec /var/lib/docker/init/dockerinit-1.0.1: cannot allocate memory`
+
 ```
 $ sudo service docker.io restart
 ```
@@ -107,6 +110,8 @@ Follow the instructions in the relevant sections of the configuration guide.
 ## Configuring Trusted Sandbox
 
 Let's go over the sections of the YAML configuration file you created in step 3 above.
+The top key of the YAML file is an environment string that can be set by `TRUSTED_SANDBOX_ENV` or `RAILS_ENV`
+environment variables.
 
 ### Docker connection
 
@@ -114,25 +119,24 @@ Trusted Sandbox uses the `docker-api` gem to communicate with docker. `docker-ap
 Linux host, and you should be good by omitting `docker_url` and `docker_cert_path` all together.
 
 ```ruby
-  # If omitted ENV['DOCKER_HOST'] is used. If it is not set, docker-api defaults are used
-  docker_url: https://192.168.59.103:2376
+# If omitted ENV['DOCKER_HOST'] is used. If it is not set, docker-api defaults are used.
+docker_url: https://192.168.59.103:2376
 
-  # If omitted ENV['DOCKER_CERT_PATH'] is used. If it is not set, docker-api defaults are used
-  docker_cert_path: ~/.boot2docker/certs/boot2docker-vm
+# If omitted ENV['DOCKER_CERT_PATH'] is used. If it is not set, docker-api defaults are used.
+docker_cert_path: ~/.boot2docker/certs/boot2docker-vm
 ```
 If you need finer control of `docker-api` configuration, you can add a `docker_options` hash entry to the
 YAML file which will override any configuration and passed through to `Docker.options`.
 
 In addition, these docker-related configuration parameters can be used:
 ```ruby
-  docker_image_name: vaharoni/trusted_sandbox:2.1.2.v1
-
-  # Optional authentication
-  docker_login:
-    user: my_user
-    password: my_password
-    email: email@email.com
+docker_image_name: vaharoni/trusted_sandbox:2.1.2.v1
 
+# Optional authentication
+docker_login:
+  user: my_user
+  password: my_password
+  email: email@email.com
 ```
 
 
@@ -170,16 +174,16 @@ Note that controlling memory swap limits and user quotas requires additional ste
 ### Execution parameters
 
 ```ruby
-  # A temporary folder under which sub folders are created and mounted to containers.
-  # The code and args exchange between the host and containers is done via these sub folders.
-  host_code_root_path: tmp/code_dirs
+# A temporary folder under which sub folders are created and mounted to containers.
+# The code and args exchange between the host and containers is done via these sub folders.
+host_code_root_path: tmp/code_dirs
 
-  # When set to true, the temporary sub folders will not be erased. This allows you to login
-  # to the container to troubleshoot issues as explained in the "Troubleshooting" section.
-  keep_code_folders: false
+# When set to true, the temporary sub folders will not be erased. This allows you to login
+# to the container to troubleshoot issues as explained in the "Troubleshooting" section.
+keep_code_folders: false
 
-  # A folder used by the UID-pool to handle locks.
-  host_uid_pool_lock_path: tmp/uid_pool_lock
+# A folder used by the UID-pool to handle locks.
+host_uid_pool_lock_path: tmp/uid_pool_lock
 ```
 
 ### Limiting swap memory
@@ -228,7 +232,7 @@ $ mount -o remount
 ```
 and reboot the server. Finally, run the following (quota is in KB):
 ```
-$ trusted_sandbox set_quotas 10000
+$ sudo trusted_sandbox set_quotas 10000
 ```
 This sets ~10MB quota on all UIDs that are in the range defined by `pool_size` and `pool_min_uid` parameters. If you
 change these configuration parameters you must rerun the `set_quotas` command.
@@ -405,6 +409,27 @@ following from your command line (adjust to your environment):
 ```
 $ docker run -it -v /home/MyUser/my_app/tmp/code_dirs/20000:/home/sandbox/src --entrypoint="/bin/bash" my_user/my_image:my_tag -s
 ```
+Note that this will also take out that specific UID from the UID-pool so that future runs don't remount the same folder.
+To release that UID back to the pool, either reset that specific UID:
+```
+$ trusted_sandbox reset_uid_pool 20000
+```
+or reset all UIDs (make sure no other containers are running):
+```
+$ trusted_sandbox reset_uid_pool
+```
+
+To avoid containers from being deleted after they finish running, set:
+```ruby
+keep_container: true
+```
+This will allow you to view containers by running `docker ps -a` and then check out container logs
+`docker logs CONTAINER_ID` or container parameters `docker inspect CONTAINER_ID`.
+
+You will need to delete containers yourself by running `docker rm CONTAINER_ID`. To delete all of your containers do:
+```
+$ docker ps -aq | xargs docker rm
+```
 
 ## Contributing
 

data/lib/trusted_sandbox/cli.rb

@@ -53,5 +53,14 @@ module TrustedSandbox
         `setquota -u #{uid} 0 #{quota_kb} 0 0 /`
       end
     end
+
+    desc 'reset_uid_pool UID', 'Release the provided UID from the UID-pool. If the UID is omitted, all UIDs that were reserved will be released, effectively resetting the pool'
+    def reset_uid_pool(uid = nil)
+      if uid
+        TrustedSandbox.uid_pool.release uid
+      else
+        TrustedSandbox.uid_pool.release_all
+      end
+    end
   end
 end

data/lib/trusted_sandbox/config/trusted_sandbox.yml

@@ -1,11 +1,11 @@
 development:
-  # # Optional login information
+  # # Optional login information for Docker Hub
   # docker_login:
   #  user:                       my_user
   #  password:                   my_password
   #  email:                      email@email.com
 
-  # # For a linux host these can remain empty
+  # # For a linux host these can typically remain commented
   # docker_url:                   https://192.168.59.103:2376
   # docker_cert_path:             ~/.boot2docker/certs/boot2docker-vm
 
@@ -24,10 +24,13 @@ development:
 
   host_code_root_path:          tmp/code_dirs
   host_uid_pool_lock_path:      tmp/uid_pool_lock
-  keep_code_folders:            false
 
-  pool_size:                    5000
-  pool_min_uid:                 20000
-  pool_timeout:                 3
-  pool_retries:                 5
-  pool_delay:                   0.5
+  keep_code_folders:            false
+  keep_containers:              false
+
+  # # It's very unlikely you'll need to change these
+  #  pool_size:                    5000
+  #  pool_min_uid:                 20000
+  #  pool_timeout:                 3
+  #  pool_retries:                 5
+  #  pool_delay:                   0.5

data/lib/trusted_sandbox/config.rb

@@ -30,7 +30,7 @@ module TrustedSandbox
                                 :memory_limit, :memory_swap_limit, :cpu_shares, :docker_image_name,
                                 :execution_timeout, :network_access, :enable_swap_limit, :enable_quotas,
                                 :container_code_path, :container_input_filename, :container_output_filename,
-                                :keep_code_folders
+                                :keep_code_folders, :keep_containers
 
     attr_reader_with_fallback :host_code_root_path, :host_uid_pool_lock_path
 

data/lib/trusted_sandbox/runner.rb

@@ -40,7 +40,7 @@ module TrustedSandbox
     end
 
     def release_uid
-      uid_pool.release(@uid) if @uid
+      uid_pool.release(@uid) if @uid and !config.keep_code_folders
     end
 
     def code_dir_path
@@ -86,7 +86,7 @@ module TrustedSandbox
     end
 
     def remove_container
-      return unless @container
+      return unless @container and !config.keep_containers
       @container.delete force: true
     end
 

data/lib/trusted_sandbox/version.rb

@@ -1,3 +1,3 @@
 module TrustedSandbox
-  VERSION = '0.0.9.pre'
+  VERSION = '0.0.10.pre'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: trusted-sandbox
 version: !ruby/object:Gem::Version
-  version: 0.0.9.pre
+  version: 0.0.10.pre
 platform: ruby
 authors:
 - Amit Aharoni