{"action":"created","comment":{"url":"https://api.github.com/repos/minrk/jupyterhub/pulls/comments/27366277","id":27366277,"diff_hunk":"@@ -128,155 +131,163 @@ c.JupyterHub.hub_port = 54321\n \n ## Security\n \n-First of all, since JupyterHub includes authentication,\n-you really shouldn't run it without SSL (HTTPS).\n-\n-To enable HTTPS, specify the path to the ssl key and/or cert\n-(some cert files also contain the key, in which case only the cert is needed):\n+First of all, since JupyterHub includes authentication and allows arbitrary code execution, you should not run it without SSL (HTTPS). This will require you to obtain an official SSL certificate or create a self-signed certificate. Once you have obtained and installed a key and certificate you need to pass their locations to JupyterHub's configuration as follows:\n \n ```python\n c.JupyterHub.ssl_key = '/path/to/my.key'\n c.JupyterHub.ssl_cert = '/path/to/my.cert'\n ```\n \n+Some cert files also contain the key, in which case only the cert is needed. It is important that these files be put in a secure location on your server.\n+\n There are two other aspects of JupyterHub network security.\n-The Hub authenticates its requests to the proxy via an environment variable,\n-`CONFIGPROXY_AUTH_TOKEN`. If you want to be able to start or restart the proxy\n-or Hub independently of each other (not always necessary),\n-you must set this environment variable before starting the server:\n \n-```bash\n-export CONFIGPROXY_AUTH_TOKEN=`openssl rand -hex 32`\n+The cookie secret is encryption key, used to encrypt the cookies used for authentication. If this value\n+changes for the Hub, all single-user servers must also be restarted. Normally, this value is stored in the\n+file `jupyterhub_cookie_secret`, which can be specified with:\n+\n+```python\n+c.JupyterHub.cookie_secret_file = '/path/to/jupyterhub_cookie_secret'\n ```\n \n-If you don't set this, the Hub will generate a random key itself,\n-which means that any time you restart the Hub you **must also restart the proxy**.\n-If the proxy is a subprocess of the Hub, this should happen automatically.\n+In most deployments of JupyterHub, you should point this to a secure location on the file system. If the\n+cookie secret file doesn't exist when the Hub starts, a new cookie secret is generated and stored in the\n+file.\n \n-The cookie secret is another key, used to encrypt the cookies used for authentication.\n-If this value changes for the Hub, all single-user servers must also be restarted.\n-Normally, this value is stored in the file `jupyterhub_cookie_secret`, which can be specified with:\n+If you would like to avoid the need for files, the value can be loaded from the `JPY_COOKIE_SECRET` env\n+variable:\n \n-```python\n-c.JupyterHub.cookie_secret_file = '/path/to/cookie_secret'\n+```bash\n+export JPY_COOKIE_SECRET=`openssl rand -hex 1024`\n ```\n \n-If the cookie secret file doesn't exist when the Hub starts,\n-a new cookie secret is generated and stored in the file.\n+The Hub authenticates its requests to the Proxy via an environment variable, `CONFIGPROXY_AUTH_TOKEN`. If\n+you want to be able to start or restart the proxy or Hub independently of each other (not always\n+necessary), you must set this environment variable before starting the server:\n \n-If you would like to avoid the need for files,\n-the value can be loaded from the `JPY_COOKIE_SECRET` env variable:\n \n ```bash\n-export JPY_COOKIE_SECRET=`openssl rand -hex 1024`\n+export CONFIGPROXY_AUTH_TOKEN=`openssl rand -hex 32`\n ```\n \n+If you don't set this, the Hub will generate a random key itself, which means that any time you restart\n+the Hub you **must also restart the Proxy**. If the proxy is a subprocess of the Hub, this should happen\n+automatically (this is the default configuration).\n+\n+**(Min: does the cookie secret and auth token env vars need to be only visible by root?)** What if other users can see them?\n+\n \n ## Configuring Authentication\n \n-The default Authenticator uses [PAM][] to authenticate system users with their username and password.\n-The default behavior of this Authenticator is to allow any users with a password on the system to login.\n-You can restrict which users are allowed to login with `Authenticator.whitelist`:\n+The default Authenticator uses [PAM][] to authenticate system users with their username and password. The\n+default behavior of this Authenticator is to allow any user with an account and password on the system to\n+login. You can restrict which users are allowed to login with `Authenticator.whitelist`:\n+\n \n ```python\n c.Authenticator.whitelist = {'mal', 'zoe', 'inara', 'kaylee'}\n ```\n \n-After starting the server, you can add and remove users in the whitelist via the `admin` panel,\n-which brings us to...\n+Admin users of JupyterHub have the ability to take actions on users' behalf, such as stopping and\n+restarting their servers, and adding and removing new users from the whitelist. Any users in the admin list are automatically added to the whitelist, if they are not already present. The set of initial Admin users can configured as follows:\n \n ```python\n c.JupyterHub.admin_users = {'mal', 'zoe'}\n ```\n \n-Any users in the admin list are automatically added to the whitelist, if they are not already present.\n+If `JupyterHub.admin_access` is True (not default), then admin users have permission to log in *as other\n+users* on their respective machines, for debugging. **You should make sure your users know if admin_access\n+is enabled.**\n \n-Admin users have the ability to take actions on users' behalf,\n-such as stopping and restarting their servers, and adding and removing new users.\n-If `JupyterHub.admin_access` is True (not default),\n-then admin users have permission to log in *as other users* on their respective machines,\n-for debugging. **You should make sure your users know if admin_access is enabled.**\n+### Adding and removing users\n \n-### adding and removing users\n+The default PAMAuthenticator is one case of a special kind of authenticator, called a LocalAuthenticator,\n+indicating that it manages users on the local system. When you add a user to the Hub, a LocalAuthenticator\n+checks if that user already exists. Normally, there will be an error telling you that the user doesn't\n+exist. If you set the configuration value\n \n-The default PAMAuthenticator is one case of a special kind of authenticator,\n-called a LocalAuthenticator,\n-indicating that it manages users on the local system.\n-When you add a user to the Hub, a LocalAuthenticator checks if that user already exists.\n-Normally, there will be an error telling you that the user doesn't exist.\n-If you set the config value\n \n ```python\n c.LocalAuthenticator.create_system_users = True\n ```\n \n-however, adding a user to the Hub that doesn't already exist on the system will result\n-in the Hub creating that user via the system `useradd` mechanism.\n-This option is typically used on hosted deployments of JupyterHub,\n-to avoid the need to manually create all your users before launching the service.\n-It is not recommended when running JupyterHub on 'real' machines with regular users.\n+however, adding a user to the Hub that doesn't already exist on the system will result in the Hub creating\n+that user via the system `useradd` mechanism. This option is typically used on hosted deployments of\n+JupyterHub (using Docker), to avoid the need to manually create all your users before launching the","path":"docs/getting-started.md","position":317,"original_position":317,"commit_id":"f55167b4ef76fb93fac4966afaa3c13b6ae64bf2","original_commit_id":"f55167b4ef76fb93fac4966afaa3c13b6ae64bf2","user":{"login":"minrk","id":151929,"avatar_url":"https://avatars.githubusercontent.com/u/151929?v=3","gravatar_id":"","url":"https://api.github.com/users/minrk","html_url":"https://github.com/minrk","followers_url":"https://api.github.com/users/minrk/followers","following_url":"https://api.github.com/users/minrk/following{/other_user}","gists_url":"https://api.github.com/users/minrk/gists{/gist_id}","starred_url":"https://api.github.com/users/minrk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/minrk/subscriptions","organizations_url":"https://api.github.com/users/minrk/orgs","repos_url":"https://api.github.com/users/minrk/repos","events_url":"https://api.github.com/users/minrk/events{/privacy}","received_events_url":"https://api.github.com/users/minrk/received_events","type":"User","site_admin":false},"body":"remove \"using Docker\", that's not accurate.","created_at":"2015-03-30T04:31:16Z","updated_at":"2015-03-30T04:31:16Z","html_url":"https://github.com/minrk/jupyterhub/pull/1#discussion_r27366277","pull_request_url":"https://api.github.com/repos/minrk/jupyterhub/pulls/1","_links":{"self":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/comments/27366277"},"html":{"href":"https://github.com/minrk/jupyterhub/pull/1#discussion_r27366277"},"pull_request":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/1"}}},"pull_request":{"url":"https://api.github.com/repos/minrk/jupyterhub/pulls/1","id":32191851,"html_url":"https://github.com/minrk/jupyterhub/pull/1","diff_url":"https://github.com/minrk/jupyterhub/pull/1.diff","patch_url":"https://github.com/minrk/jupyterhub/pull/1.patch","issue_url":"https://api.github.com/repos/minrk/jupyterhub/issues/1","number":1,"state":"open","locked":false,"title":"Getting started edits","user":{"login":"ellisonbg","id":27600,"avatar_url":"https://avatars.githubusercontent.com/u/27600?v=3","gravatar_id":"","url":"https://api.github.com/users/ellisonbg","html_url":"https://github.com/ellisonbg","followers_url":"https://api.github.com/users/ellisonbg/followers","following_url":"https://api.github.com/users/ellisonbg/following{/other_user}","gists_url":"https://api.github.com/users/ellisonbg/gists{/gist_id}","starred_url":"https://api.github.com/users/ellisonbg/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ellisonbg/subscriptions","organizations_url":"https://api.github.com/users/ellisonbg/orgs","repos_url":"https://api.github.com/users/ellisonbg/repos","events_url":"https://api.github.com/users/ellisonbg/events{/privacy}","received_events_url":"https://api.github.com/users/ellisonbg/received_events","type":"User","site_admin":false},"body":"Some edits to the getting started.","created_at":"2015-03-30T00:44:47Z","updated_at":"2015-03-30T04:31:16Z","closed_at":null,"merged_at":null,"merge_commit_sha":"a01b8f17d27bb767160f31e41d3bb2f3c90876ac","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/minrk/jupyterhub/pulls/1/commits","review_comments_url":"https://api.github.com/repos/minrk/jupyterhub/pulls/1/comments","review_comment_url":"https://api.github.com/repos/minrk/jupyterhub/pulls/comments{/number}","comments_url":"https://api.github.com/repos/minrk/jupyterhub/issues/1/comments","statuses_url":"https://api.github.com/repos/minrk/jupyterhub/statuses/f55167b4ef76fb93fac4966afaa3c13b6ae64bf2","head":{"label":"ellisonbg:getting-started-edits","ref":"getting-started-edits","sha":"f55167b4ef76fb93fac4966afaa3c13b6ae64bf2","user":{"login":"ellisonbg","id":27600,"avatar_url":"https://avatars.githubusercontent.com/u/27600?v=3","gravatar_id":"","url":"https://api.github.com/users/ellisonbg","html_url":"https://github.com/ellisonbg","followers_url":"https://api.github.com/users/ellisonbg/followers","following_url":"https://api.github.com/users/ellisonbg/following{/other_user}","gists_url":"https://api.github.com/users/ellisonbg/gists{/gist_id}","starred_url":"https://api.github.com/users/ellisonbg/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ellisonbg/subscriptions","organizations_url":"https://api.github.com/users/ellisonbg/orgs","repos_url":"https://api.github.com/users/ellisonbg/repos","events_url":"https://api.github.com/users/ellisonbg/events{/privacy}","received_events_url":"https://api.github.com/users/ellisonbg/received_events","type":"User","site_admin":false},"repo":{"id":23170491,"name":"jupyterhub","full_name":"ellisonbg/jupyterhub","owner":{"login":"ellisonbg","id":27600,"avatar_url":"https://avatars.githubusercontent.com/u/27600?v=3","gravatar_id":"","url":"https://api.github.com/users/ellisonbg","html_url":"https://github.com/ellisonbg","followers_url":"https://api.github.com/users/ellisonbg/followers","following_url":"https://api.github.com/users/ellisonbg/following{/other_user}","gists_url":"https://api.github.com/users/ellisonbg/gists{/gist_id}","starred_url":"https://api.github.com/users/ellisonbg/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ellisonbg/subscriptions","organizations_url":"https://api.github.com/users/ellisonbg/orgs","repos_url":"https://api.github.com/users/ellisonbg/repos","events_url":"https://api.github.com/users/ellisonbg/events{/privacy}","received_events_url":"https://api.github.com/users/ellisonbg/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/ellisonbg/jupyterhub","description":"Multi-user server for Jupyter notebooks","fork":true,"url":"https://api.github.com/repos/ellisonbg/jupyterhub","forks_url":"https://api.github.com/repos/ellisonbg/jupyterhub/forks","keys_url":"https://api.github.com/repos/ellisonbg/jupyterhub/keys{/key_id}","collaborators_url":"https://api.github.com/repos/ellisonbg/jupyterhub/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/ellisonbg/jupyterhub/teams","hooks_url":"https://api.github.com/repos/ellisonbg/jupyterhub/hooks","issue_events_url":"https://api.github.com/repos/ellisonbg/jupyterhub/issues/events{/number}","events_url":"https://api.github.com/repos/ellisonbg/jupyterhub/events","assignees_url":"https://api.github.com/repos/ellisonbg/jupyterhub/assignees{/user}","branches_url":"https://api.github.com/repos/ellisonbg/jupyterhub/branches{/branch}","tags_url":"https://api.github.com/repos/ellisonbg/jupyterhub/tags","blobs_url":"https://api.github.com/repos/ellisonbg/jupyterhub/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/ellisonbg/jupyterhub/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/ellisonbg/jupyterhub/git/refs{/sha}","trees_url":"https://api.github.com/repos/ellisonbg/jupyterhub/git/trees{/sha}","statuses_url":"https://api.github.com/repos/ellisonbg/jupyterhub/statuses/{sha}","languages_url":"https://api.github.com/repos/ellisonbg/jupyterhub/languages","stargazers_url":"https://api.github.com/repos/ellisonbg/jupyterhub/stargazers","contributors_url":"https://api.github.com/repos/ellisonbg/jupyterhub/contributors","subscribers_url":"https://api.github.com/repos/ellisonbg/jupyterhub/subscribers","subscription_url":"https://api.github.com/repos/ellisonbg/jupyterhub/subscription","commits_url":"https://api.github.com/repos/ellisonbg/jupyterhub/commits{/sha}","git_commits_url":"https://api.github.com/repos/ellisonbg/jupyterhub/git/commits{/sha}","comments_url":"https://api.github.com/repos/ellisonbg/jupyterhub/comments{/number}","issue_comment_url":"https://api.github.com/repos/ellisonbg/jupyterhub/issues/comments{/number}","contents_url":"https://api.github.com/repos/ellisonbg/jupyterhub/contents/{+path}","compare_url":"https://api.github.com/repos/ellisonbg/jupyterhub/compare/{base}...{head}","merges_url":"https://api.github.com/repos/ellisonbg/jupyterhub/merges","archive_url":"https://api.github.com/repos/ellisonbg/jupyterhub/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/ellisonbg/jupyterhub/downloads","issues_url":"https://api.github.com/repos/ellisonbg/jupyterhub/issues{/number}","pulls_url":"https://api.github.com/repos/ellisonbg/jupyterhub/pulls{/number}","milestones_url":"https://api.github.com/repos/ellisonbg/jupyterhub/milestones{/number}","notifications_url":"https://api.github.com/repos/ellisonbg/jupyterhub/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/ellisonbg/jupyterhub/labels{/name}","releases_url":"https://api.github.com/repos/ellisonbg/jupyterhub/releases{/id}","created_at":"2014-08-21T01:52:07Z","updated_at":"2014-09-12T02:35:35Z","pushed_at":"2015-03-30T00:43:51Z","git_url":"git://github.com/ellisonbg/jupyterhub.git","ssh_url":"git@github.com:ellisonbg/jupyterhub.git","clone_url":"https://github.com/ellisonbg/jupyterhub.git","svn_url":"https://github.com/ellisonbg/jupyterhub","homepage":"","size":212,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"minrk:getting-started","ref":"getting-started","sha":"21116c273e3c7e5e1573c5f691eb995d716d0662","user":{"login":"minrk","id":151929,"avatar_url":"https://avatars.githubusercontent.com/u/151929?v=3","gravatar_id":"","url":"https://api.github.com/users/minrk","html_url":"https://github.com/minrk","followers_url":"https://api.github.com/users/minrk/followers","following_url":"https://api.github.com/users/minrk/following{/other_user}","gists_url":"https://api.github.com/users/minrk/gists{/gist_id}","starred_url":"https://api.github.com/users/minrk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/minrk/subscriptions","organizations_url":"https://api.github.com/users/minrk/orgs","repos_url":"https://api.github.com/users/minrk/repos","events_url":"https://api.github.com/users/minrk/events{/privacy}","received_events_url":"https://api.github.com/users/minrk/received_events","type":"User","site_admin":false},"repo":{"id":21696764,"name":"jupyterhub","full_name":"minrk/jupyterhub","owner":{"login":"minrk","id":151929,"avatar_url":"https://avatars.githubusercontent.com/u/151929?v=3","gravatar_id":"","url":"https://api.github.com/users/minrk","html_url":"https://github.com/minrk","followers_url":"https://api.github.com/users/minrk/followers","following_url":"https://api.github.com/users/minrk/following{/other_user}","gists_url":"https://api.github.com/users/minrk/gists{/gist_id}","starred_url":"https://api.github.com/users/minrk/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/minrk/subscriptions","organizations_url":"https://api.github.com/users/minrk/orgs","repos_url":"https://api.github.com/users/minrk/repos","events_url":"https://api.github.com/users/minrk/events{/privacy}","received_events_url":"https://api.github.com/users/minrk/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/minrk/jupyterhub","description":"Multi-user server for Jupyter notebooks","fork":true,"url":"https://api.github.com/repos/minrk/jupyterhub","forks_url":"https://api.github.com/repos/minrk/jupyterhub/forks","keys_url":"https://api.github.com/repos/minrk/jupyterhub/keys{/key_id}","collaborators_url":"https://api.github.com/repos/minrk/jupyterhub/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/minrk/jupyterhub/teams","hooks_url":"https://api.github.com/repos/minrk/jupyterhub/hooks","issue_events_url":"https://api.github.com/repos/minrk/jupyterhub/issues/events{/number}","events_url":"https://api.github.com/repos/minrk/jupyterhub/events","assignees_url":"https://api.github.com/repos/minrk/jupyterhub/assignees{/user}","branches_url":"https://api.github.com/repos/minrk/jupyterhub/branches{/branch}","tags_url":"https://api.github.com/repos/minrk/jupyterhub/tags","blobs_url":"https://api.github.com/repos/minrk/jupyterhub/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/minrk/jupyterhub/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/minrk/jupyterhub/git/refs{/sha}","trees_url":"https://api.github.com/repos/minrk/jupyterhub/git/trees{/sha}","statuses_url":"https://api.github.com/repos/minrk/jupyterhub/statuses/{sha}","languages_url":"https://api.github.com/repos/minrk/jupyterhub/languages","stargazers_url":"https://api.github.com/repos/minrk/jupyterhub/stargazers","contributors_url":"https://api.github.com/repos/minrk/jupyterhub/contributors","subscribers_url":"https://api.github.com/repos/minrk/jupyterhub/subscribers","subscription_url":"https://api.github.com/repos/minrk/jupyterhub/subscription","commits_url":"https://api.github.com/repos/minrk/jupyterhub/commits{/sha}","git_commits_url":"https://api.github.com/repos/minrk/jupyterhub/git/commits{/sha}","comments_url":"https://api.github.com/repos/minrk/jupyterhub/comments{/number}","issue_comment_url":"https://api.github.com/repos/minrk/jupyterhub/issues/comments{/number}","contents_url":"https://api.github.com/repos/minrk/jupyterhub/contents/{+path}","compare_url":"https://api.github.com/repos/minrk/jupyterhub/compare/{base}...{head}","merges_url":"https://api.github.com/repos/minrk/jupyterhub/merges","archive_url":"https://api.github.com/repos/minrk/jupyterhub/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/minrk/jupyterhub/downloads","issues_url":"https://api.github.com/repos/minrk/jupyterhub/issues{/number}","pulls_url":"https://api.github.com/repos/minrk/jupyterhub/pulls{/number}","milestones_url":"https://api.github.com/repos/minrk/jupyterhub/milestones{/number}","notifications_url":"https://api.github.com/repos/minrk/jupyterhub/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/minrk/jupyterhub/labels{/name}","releases_url":"https://api.github.com/repos/minrk/jupyterhub/releases{/id}","created_at":"2014-07-10T14:17:50Z","updated_at":"2015-03-07T22:46:04Z","pushed_at":"2015-03-30T00:44:47Z","git_url":"git://github.com/minrk/jupyterhub.git","ssh_url":"git@github.com:minrk/jupyterhub.git","clone_url":"https://github.com/minrk/jupyterhub.git","svn_url":"https://github.com/minrk/jupyterhub","homepage":"","size":1214,"stargazers_count":0,"watchers_count":0,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":1,"forks":0,"open_issues":1,"watchers":0,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/1"},"html":{"href":"https://github.com/minrk/jupyterhub/pull/1"},"issue":{"href":"https://api.github.com/repos/minrk/jupyterhub/issues/1"},"comments":{"href":"https://api.github.com/repos/minrk/jupyterhub/issues/1/comments"},"review_comments":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/1/comments"},"review_comment":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/minrk/jupyterhub/pulls/1/commits"},"statuses":{"href":"https://api.github.com/repos/minrk/jupyterhub/statuses/f55167b4ef76fb93fac4966afaa3c13b6ae64bf2"}}}}