Merge pull request #34 from consideRatio/pr/add-hub-read-tighten-serv…

…ers-permissions

Minor tweaks to the readme

README.md

@@ -24,7 +24,7 @@ Prior to JupyterHub 2.0, the `jupyterhub-idle-culler` required full administrati
 in order to have sufficient permissions to stop servers on behalf of users.
 
 JupyterHub 2.0 introduces [scopes][] to allow for more fine-grained permission control.
-This means that the cull-idle service does not need full administrative privileges anymore.
+This means that the configured culler service does not need full administrative privileges anymore.
 It can be assigned only the permissions it needs.
 
 [scopes]: https://jupyterhub.readthedocs.io/en/latest/rbac/scopes.html#available-scopes
@@ -33,22 +33,23 @@ It can be assigned only the permissions it needs.
 
 - `list:users` - access to the user list API, our source of information about who to cull
 - `read:users:activity` - read the last_activity field of the user
-- `servers` - management of servers (this includes stopping servers and reading the server model)
+- `delete:servers` - management of servers (this includes stopping servers)
 - `admin:users` (**optional**) - only needed if using `--cull-users`
 
 To assign the service the appropriate permissions, declare a role in your `jupyterhub_config.py`:
 
 ```python
 c.JupyterHub.load_roles = [
     {
-        "name": "cull-idle",
+        "name": "jupyterhub-idle-culler-role",
         "scopes": [
             "list:users",
             "read:users:activity",
-            "servers",
+            "delete:servers",
             # "admin:users", # if using --cull-users
         ],
-        "services": ["idle-culler"], # assign our service to this role, so it has these permissions
+        # assignment of role's permissions to:
+        "services": ["jupyterhub-idle-culler-service"],
     }
 ]
 ```
@@ -61,57 +62,55 @@ Service to the `c.JupyterHub.services` list:
 ```python
 c.JupyterHub.services = [
     {
-        'name': 'idle-culler',
-        # 'admin': True,
-        'command': [
+        "name": "jupyterhub-idle-culler-service",
+        "command": [
             sys.executable,
-            '-m', 'jupyterhub_idle_culler',
-            '--timeout=3600'
+            "-m", "jupyterhub_idle_culler",
+            "--timeout=3600",
         ],
+        # "admin": True,
     }
 ]
 ```
 
 where:
 
-- `'admin': True` indicates that the Service requires admin permissions so
-  it can shut down arbitrary user notebooks
-  (only for jupyterhub < 2.0; see [above][permissions]), and
-- `'command'` indicates that the Service will be managed by the Hub.
+- `"command"` indicates that the Service will be managed by the Hub, and
+- `"admin": True` grants admin permissions to this Service and is only meant for
+  use with jupyterhub < 2.0; see [above][permissions].
 
 ### As a standalone script
 
 `jupyterhub-idle-culler` can also be run as a standalone script. It can
 access the hub's api with a service token.
 
-Register the service token with JupyterHub in jupyterhub_config.py:
+Register the service token with JupyterHub in `jupyterhub_config.py`:
 
 ```python
 c.JupyterHub.services = [
     {
-        'name': 'idle-culler',
-        # 'admin': True,
-        'api_token': '...',
+        "name": "jupyterhub-idle-culler-service",
+        "api_token": "...",
+        # "admin": True,
     }
 ]
 ```
 
 where:
 
-- `'admin': True` indicates that the Service requires admin permissions so
-  it can shut down arbitrary user notebooks
-  (only for jupyterhub < 2.0; see [above][permissions]), and
-- `'api_token'` contains a secret token, e.g. generated by `openssl rand -hex 32`
+- `"api_token"` contains a secret token, e.g. generated by `openssl rand -hex 32`, and
+- `"admin": True` grants admin permissions to this Service and is only meant for
+  use with jupyterhub < 2.0; see [above][permissions].
 
 and store the same token in a `JUPYTERHUB_API_TOKEN` environment variable.
-Then start `jupyterhub-idle-culler` manually
+Then start `jupyterhub-idle-culler` manually.
 
 ```bash
 export JUPYTERHUB_API_TOKEN=api_token_above...
 python3 -m jupyterhub-idle-culler [--timeout=900] [--url=http://localhost:8081/hub/api]
 ```
 
-The command line interface also gives a quick overview of the different options for configuration.
+## Command line flags
 
 ```
   --api-page-size                  Number of users to request per page, when
@@ -123,6 +122,8 @@ The command line interface also gives a quick overview of the different options
                                    same time can slow down the Hub, so limit
                                    the number of API requests we have
                                    outstanding at any given time. (default 10)
+  --cull-admin-users               Whether admin users should be culled (only
+                                   if --cull-users=true). (default True)
   --cull-every                     The interval (in seconds) for checking for
                                    idle servers to cull. (default 0)
   --cull-users                     Cull users in addition to servers.  This is