From 3c279c4fadfc4c08a3119f39317865a1ef3dcff1 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Fri, 13 May 2016 12:22:19 -0700 Subject: [PATCH 1/4] Create a man page for ourselves! --- docs/cli-help.txt | 340 +++++++++++++++++++++++++++++++++++++++++++ docs/man/certbot.rst | 2 +- 2 files changed, 341 insertions(+), 1 deletion(-) create mode 100644 docs/cli-help.txt diff --git a/docs/cli-help.txt b/docs/cli-help.txt new file mode 100644 index 000000000..cb4bace58 --- /dev/null +++ b/docs/cli-help.txt @@ -0,0 +1,340 @@ +usage: + certbot [SUBCOMMAND] [options] [-d domain] [-d domain] ... + +Certbot can obtain and install HTTPS/TLS/SSL certificates. By default, +it will attempt to use a webserver both for obtaining and installing the +cert. Major SUBCOMMANDS are: + + (default) run Obtain & install a cert in your current webserver + certonly Obtain cert, but do not install it (aka "auth") + install Install a previously obtained cert in a server + renew Renew previously obtained certs that are near expiry + revoke Revoke a previously obtained certificate + rollback Rollback server configuration changes made during install + config_changes Show changes made to server config during installation + plugins Display information about installed plugins + +optional arguments: + -h, --help show this help message and exit + -c CONFIG_FILE, --config CONFIG_FILE + config file path (default: None) + -v, --verbose This flag can be used multiple times to incrementally + increase the verbosity of output, e.g. -vvv. (default: + -3) + -t, --text Use the text output instead of the curses UI. + (default: False) + -n, --non-interactive, --noninteractive + Run without ever asking for user input. This may + require additional command line flags; the client will + try to explain which ones are required if it finds one + missing (default: False) + --dry-run Perform a test run of the client, obtaining test + (invalid) certs but not saving them to disk. This can + currently only be used with the 'certonly' and 'renew' + subcommands. Note: Although --dry-run tries to avoid + making any persistent changes on a system, it is not + completely side-effect free: if used with webserver + authenticator plugins like apache and nginx, it makes + and then reverts temporary config changes in order to + obtain test certs, and reloads webservers to deploy + and then roll back those changes. It also calls --pre- + hook and --post-hook commands if they are defined + because they may be necessary to accurately simulate + renewal. --renew-hook commands are not called. + (default: False) + --register-unsafely-without-email + Specifying this flag enables registering an account + with no email address. This is strongly discouraged, + because in the event of key loss or account compromise + you will irrevocably lose access to your account. You + will also be unable to receive notice about impending + expiration or revocation of your certificates. Updates + to the Subscriber Agreement will still affect you, and + will be effective 14 days after posting an update to + the web site. (default: False) + -m EMAIL, --email EMAIL + Email used for registration and recovery contact. + (default: None) + -d DOMAIN, --domains DOMAIN, --domain DOMAIN + Domain names to apply. For multiple domains you can + use multiple -d flags or enter a comma separated list + of domains as a parameter. (default: []) + --user-agent USER_AGENT + Set a custom user agent string for the client. User + agent strings allow the CA to collect high level + statistics about success rates by OS and plugin. If + you wish to hide your server OS version from the Let's + Encrypt server, set this to "". (default: None) + +automation: + Arguments for automating execution & other tweaks + + --keep-until-expiring, --keep, --reinstall + If the requested cert matches an existing cert, always + keep the existing one until it is due for renewal (for + the 'run' subcommand this means reinstall the existing + cert) (default: False) + --expand If an existing cert covers some subset of the + requested names, always expand and replace it with the + additional names. (default: False) + --version show program's version number and exit + --force-renewal, --renew-by-default + If a certificate already exists for the requested + domains, renew it now, regardless of whether it is + near expiry. (Often --keep-until-expiring is more + appropriate). Also implies --expand. (default: False) + --allow-subset-of-names + When performing domain validation, do not consider it + a failure if authorizations can not be obtained for a + strict subset of the requested domains. This may be + useful for allowing renewals for multiple domains to + succeed even if some domains no longer point at this + system. This option cannot be used with --csr. + (default: False) + --agree-tos Agree to the ACME Subscriber Agreement (default: + False) + --account ACCOUNT_ID Account ID to use (default: None) + --duplicate Allow making a certificate lineage that duplicates an + existing one (both can be renewed in parallel) + (default: False) + --os-packages-only (letsencrypt-auto only) install OS package + dependencies and then stop (default: False) + --no-self-upgrade (letsencrypt-auto only) prevent the letsencrypt-auto + script from upgrading itself to newer released + versions (default: False) + -q, --quiet Silence all output except errors. Useful for + automation via cron. Implies --non-interactive. + (default: False) + +testing: + The following flags are meant for testing purposes only! Do NOT change + them, unless you really know what you're doing! + + --debug Show tracebacks in case of errors, and allow + letsencrypt-auto execution on experimental platforms + (default: False) + --no-verify-ssl Disable SSL certificate verification. (default: False) + --tls-sni-01-port TLS_SNI_01_PORT + Port number to perform tls-sni-01 challenge. Boulder + in testing mode defaults to 5001. (default: 443) + --http-01-port HTTP01_PORT + Port used in the SimpleHttp challenge. (default: 80) + --break-my-certs Be willing to replace or renew valid certs with + invalid (testing/staging) certs (default: False) + --test-cert, --staging + Use the staging server to obtain test (invalid) certs; + equivalent to --server https://acme- + staging.api.letsencrypt.org/directory (default: False) + +security: + Security parameters & server settings + + --rsa-key-size N Size of the RSA key. (default: 2048) + --redirect Automatically redirect all HTTP traffic to HTTPS for + the newly authenticated vhost. (default: None) + --no-redirect Do not automatically redirect all HTTP traffic to + HTTPS for the newly authenticated vhost. (default: + None) + --hsts Add the Strict-Transport-Security header to every HTTP + response. Forcing browser to use always use SSL for + the domain. Defends against SSL Stripping. (default: + False) + --no-hsts Do not automatically add the Strict-Transport-Security + header to every HTTP response. (default: False) + --uir Add the "Content-Security-Policy: upgrade-insecure- + requests" header to every HTTP response. Forcing the + browser to use https:// for every http:// resource. + (default: None) + --no-uir Do not automatically set the "Content-Security-Policy: + upgrade-insecure-requests" header to every HTTP + response. (default: None) + --strict-permissions Require that all configuration files are owned by the + current user; only needed if your config is somewhere + unsafe like /tmp/ (default: False) + +renew: + The 'renew' subcommand will attempt to renew all certificates (or more + precisely, certificate lineages) you have previously obtained if they are + close to expiry, and print a summary of the results. By default, 'renew' + will reuse the options used to create obtain or most recently successfully + renew each certificate lineage. You can try it with `--dry-run` first. For + more fine-grained control, you can renew individual lineages with the + `certonly` subcommand. Hooks are available to run commands before and + after renewal; see https://certbot.eff.org/docs/using.html#renewal for + more information on these. + + --pre-hook PRE_HOOK Command to be run in a shell before obtaining any + certificates. Intended primarily for renewal, where it + can be used to temporarily shut down a webserver that + might conflict with the standalone plugin. This will + only be called if a certificate is actually to be + obtained/renewed. (default: None) + --post-hook POST_HOOK + Command to be run in a shell after attempting to + obtain/renew certificates. Can be used to deploy + renewed certificates, or to restart any servers that + were stopped by --pre-hook. (default: None) + --renew-hook RENEW_HOOK + Command to be run in a shell once for each + successfully renewed certificate.For this command, the + shell variable $RENEWED_LINEAGE will point to + theconfig live subdirectory containing the new certs + and keys; the shell variable $RENEWED_DOMAINS will + contain a space-delimited list of renewed cert domains + (default: None) + +certonly: + Options for modifying how a cert is obtained + + --csr CSR Path to a Certificate Signing Request (CSR) in DER + format; note that the .csr file *must* contain a + Subject Alternative Name field for each domain you + want certified. Currently --csr only works with the + 'certonly' subcommand' (default: None) + +install: + Options for modifying how a cert is deployed + +revoke: + Options for revocation of certs + +rollback: + Options for reverting config changes + + --checkpoints N Revert configuration N number of checkpoints. + (default: 1) + +plugins: + Plugin options + + --init Initialize plugins. (default: False) + --prepare Initialize and prepare plugins. (default: False) + --authenticators Limit to authenticator plugins only. (default: None) + --installers Limit to installer plugins only. (default: None) + +config_changes: + Options for showing a history of config changes + + --num NUM How many past revisions you want to be displayed + (default: None) + +paths: + Arguments changing execution paths & servers + + --cert-path CERT_PATH + Path to where cert is saved (with auth --csr), + installed from or revoked. (default: None) + --key-path KEY_PATH Path to private key for cert installation or + revocation (if account key is missing) (default: None) + --fullchain-path FULLCHAIN_PATH + Accompanying path to a full certificate chain (cert + plus chain). (default: None) + --chain-path CHAIN_PATH + Accompanying path to a certificate chain. (default: + None) + --config-dir CONFIG_DIR + Configuration directory. (default: /etc/letsencrypt) + --work-dir WORK_DIR Working directory. (default: /var/lib/letsencrypt) + --logs-dir LOGS_DIR Logs directory. (default: /var/log/letsencrypt) + --server SERVER ACME Directory Resource URI. (default: + https://acme-v01.api.letsencrypt.org/directory) + +plugins: + Certbot client supports an extensible plugins architecture. See 'certbot + plugins' for a list of all installed plugins and their names. You can + force a particular plugin by setting options provided below. Running + --help will list flags specific to that plugin. + + -a AUTHENTICATOR, --authenticator AUTHENTICATOR + Authenticator plugin name. (default: None) + -i INSTALLER, --installer INSTALLER + Installer plugin name (also used to find domains). + (default: None) + --configurator CONFIGURATOR + Name of the plugin that is both an authenticator and + an installer. Should not be used together with + --authenticator or --installer. (default: None) + --apache Obtain and install certs using Apache (default: False) + --nginx Obtain and install certs using Nginx (default: False) + --standalone Obtain certs using a "standalone" webserver. (default: + False) + --manual Provide laborious manual instructions for obtaining a + cert (default: False) + --webroot Obtain certs by placing files in a webroot directory. + (default: False) + +nginx: + Nginx Web Server - currently doesn't work + + --nginx-server-root NGINX_SERVER_ROOT + Nginx server root directory. (default: /etc/nginx) + --nginx-ctl NGINX_CTL + Path to the 'nginx' binary, used for 'configtest' and + retrieving nginx version number. (default: nginx) + +standalone: + Automatically use a temporary webserver + + --standalone-supported-challenges STANDALONE_SUPPORTED_CHALLENGES + Supported challenges. Preferred in the order they are + listed. (default: tls-sni-01,http-01) + +manual: + Manually configure an HTTP server + + --manual-test-mode Test mode. Executes the manual command in subprocess. + (default: False) + --manual-public-ip-logging-ok + Automatically allows public IP logging. (default: + False) + +webroot: + Place files in webroot directory + + --webroot-path WEBROOT_PATH, -w WEBROOT_PATH + public_html / webroot path. This can be specified + multiple times to handle different domains; each + domain will have the webroot path that preceded it. + For instance: `-w /var/www/example -d example.com -d + www.example.com -w /var/www/thing -d thing.net -d + m.thing.net` (default: []) + --webroot-map WEBROOT_MAP + JSON dictionary mapping domains to webroot paths; this + implies -d for each entry. You may need to escape this + from your shell. E.g.: --webroot-map + '{"eg1.is,m.eg1.is":"/www/eg1/", "eg2.is":"/www/eg2"}' + This option is merged with, but takes precedence over, + -w / -d entries. At present, if you put webroot-map in + a config file, it needs to be on a single line, like: + webroot-map = {"example.com":"/var/www"}. (default: + {}) + +apache: + Apache Web Server - Alpha + + --apache-enmod APACHE_ENMOD + Path to the Apache 'a2enmod' binary. (default: + a2enmod) + --apache-dismod APACHE_DISMOD + Path to the Apache 'a2dismod' binary. (default: + a2dismod) + --apache-le-vhost-ext APACHE_LE_VHOST_EXT + SSL vhost configuration extension. (default: -le- + ssl.conf) + --apache-server-root APACHE_SERVER_ROOT + Apache server root directory. (default: /etc/apache2) + --apache-vhost-root APACHE_VHOST_ROOT + Apache server VirtualHost configuration root (default: + /etc/apache2/sites-available) + --apache-challenge-location APACHE_CHALLENGE_LOCATION + Directory path for challenge configuration. (default: + /etc/apache2) + --apache-handle-modules APACHE_HANDLE_MODULES + Let installer handle enabling required modules for + you.(Only Ubuntu/Debian currently) (default: True) + --apache-handle-sites APACHE_HANDLE_SITES + Let installer handle enabling sites for you.(Only + Ubuntu/Debian currently) (default: True) + +null: + Null Installer diff --git a/docs/man/certbot.rst b/docs/man/certbot.rst index 7382d7811..8fb03db49 100644 --- a/docs/man/certbot.rst +++ b/docs/man/certbot.rst @@ -1 +1 @@ -.. program-output:: certbot --help all +.. literalinclude:: cli-help.txt From c55d8e4741bfcd02934c37902f9ba6edf33cb8ee Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Fri, 13 May 2016 12:22:35 -0700 Subject: [PATCH 2/4] Build the text for the man page at release --- tools/release.sh | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/release.sh b/tools/release.sh index 8c2d04cd4..abaad09ff 100755 --- a/tools/release.sh +++ b/tools/release.sh @@ -145,6 +145,9 @@ pip install \ kill $! cd ~- +# get a snapshot of the CLI help for the docs +certbot --help all > docs/cli-help.txt + # freeze before installing anything else, so that we know end-user KGS # make sure "twine upload" doesn't catch "kgs" if [ -d ../kgs ] ; then @@ -197,7 +200,7 @@ mv letsencrypt-auto-source/letsencrypt-auto.asc letsencrypt-auto-source/certbot- cp -p letsencrypt-auto-source/letsencrypt-auto certbot-auto cp -p letsencrypt-auto-source/letsencrypt-auto letsencrypt-auto -git add certbot-auto letsencrypt-auto letsencrypt-auto-source +git add certbot-auto letsencrypt-auto letsencrypt-auto-source docs/cli-help.txt git diff --cached git commit --gpg-sign="$RELEASE_GPG_KEY" -m "Release $version" git tag --local-user "$RELEASE_GPG_KEY" --sign --message "Release $version" "$tag" From f16104e3cb1b1de34d4683853d3b255229c9ae4d Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Fri, 13 May 2016 12:22:55 -0700 Subject: [PATCH 3/4] Lots of doc cleanups --- README.rst | 14 +++++--- certbot/cli.py | 3 +- docs/contributing.rst | 2 +- docs/intro.rst | 6 ++-- docs/using.rst | 78 +++++++++++++++---------------------------- 5 files changed, 42 insertions(+), 61 deletions(-) diff --git a/README.rst b/README.rst index 20b49083f..c71079f9a 100644 --- a/README.rst +++ b/README.rst @@ -31,14 +31,17 @@ Contributing If you'd like to contribute to this project please read `Developer Guide `_. +.. _installation: + Installation ------------ -If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS, you can install -it from there, and run it by typing ``certbot`` (or ``letsencrypt``). -Because not all operating systems have packages yet, we provide a temporary -solution via the ``certbot-auto`` wrapper script, which obtains some -dependencies from your OS and puts others in a python virtual environment:: +If ``certbot`` (or ``letsencrypt``) is packaged for your Unix OS (visit +certbot.eff.org_ to find out), you can install it +from there, and run it by typing ``certbot`` (or ``letsencrypt``). Because +not all operating systems have packages yet, we provide a temporary solution +via the ``certbot-auto`` wrapper script, which obtains some dependencies from +your OS and puts others in a python virtual environment:: user@webserver:~$ wget https://dl.eff.org/certbot-auto user@webserver:~$ chmod a+x ./certbot-auto @@ -188,3 +191,4 @@ Current Features .. _Freenode: https://webchat.freenode.net?channels=%23letsencrypt .. _OFTC: https://webchat.oftc.net?channels=%23certbot .. _client-dev: https://groups.google.com/a/letsencrypt.org/forum/#!forum/client-dev +.. _certbot.eff.org: https://certbot.eff.org/ diff --git a/certbot/cli.py b/certbot/cli.py index 90e86a751..65715ac57 100644 --- a/certbot/cli.py +++ b/certbot/cli.py @@ -745,7 +745,8 @@ def prepare_and_parse_args(plugins, args, detect_defaults=False): " certificate lineage. You can try it with `--dry-run` first. For" " more fine-grained control, you can renew individual lineages with" " the `certonly` subcommand. Hooks are available to run commands " - " before and after renewal; see XXX for more information on these.") + " before and after renewal; see" + " https://certbot.eff.org/docs/using.html#renewal for more information on these.") helpful.add( "renew", "--pre-hook", diff --git a/docs/contributing.rst b/docs/contributing.rst index 49e9e146d..b56a04c7d 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -333,7 +333,7 @@ commands: .. code-block:: shell - make -C docs clean html + make -C docs clean html man This should generate documentation in the ``docs/_build/html`` directory. diff --git a/docs/intro.rst b/docs/intro.rst index 188ff4302..2fffbec68 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -1,6 +1,6 @@ -============ -Introduction -============ +===================== +README / Introduction +===================== .. include:: ../README.rst .. include:: ../CHANGES.rst diff --git a/docs/using.rst b/docs/using.rst index 997134de5..6558e9e16 100644 --- a/docs/using.rst +++ b/docs/using.rst @@ -5,56 +5,28 @@ User Guide .. contents:: Table of Contents :local: -.. _installation: +Getting Certbot +=============== -Installation -============ +To get specific instructions for installing Certbot on your OS, we recommend +visiting certbot.eff.org_. If you're offline, you can find some general +instructions `in the README / Introduction `__ + +__ installation_ +.. _certbot.eff.org: https://certbot.eff.org .. _certbot-auto: -certbot-auto ----------------- +The name of the certbot command +------------------------------- -``certbot-auto`` is a wrapper which installs some dependencies -from your OS standard package repositories (e.g. using `apt-get` or -`yum`), and for other dependencies it sets up a virtualized Python -environment with packages downloaded from PyPI [#venv]_. It also -provides automated updates. - -To install and run the client, just type... - -.. code-block:: shell - - ./certbot-auto - -.. hint:: The Let's Encrypt servers enforce rate - limits on the number of certificates issued for one domain. It is recommended - to initially use the test server via `--test-cert` until you get the desired - certificates. - -Throughout the documentation, whenever you see references to -``certbot`` script/binary, you can substitute in -``certbot-auto``. For example, to get basic help you would type: - -.. code-block:: shell - - ./certbot-auto --help - -or for full help, type: - -.. code-block:: shell - - ./certbot-auto --help all - - -``certbot-auto`` is the recommended method of running the Certbot -client beta releases on systems that don't have a packaged version. Debian, -Arch Linux, Gentoo, FreeBSD, and OpenBSD now have native packages, so on those -systems you can just install ``certbot`` (and perhaps -``certbot-apache``). If you'd like to run the latest copy from Git, or -run your own locally modified copy of the client, follow the instructions in -the :doc:`contributing`. Some `other methods of installation`_ are discussed -below. +Many platforms now have native packages that give you a ``certbot`` or (for +older packages) ``letsencrypt`` command you can run. On others, the +``certbot-auto`` / ``letsencrypt-auto`` installer and wrapper script is a +stand-in. Throughout the documentation, whenever you see references to +``certbot`` script/binary, you should substitute in the name of the command +that certbot.eff.org_ told you to use on your system (``certbot``, +``letsencrypt``, or ``certbot-auto``). Plugins @@ -275,17 +247,21 @@ Certbot is working hard on improving the renewal process, and we apologize for any inconveniences you encounter in integrating these commands into your individual environment. +.. _command-line: + +Command line options +==================== + +Certbot supports a lot of command line options. Here's the full list, from +``certbot --help all``: + +.. literalinclude:: cli-help.txt .. _where-certs: Where are my certificates? ========================== -First of all, we encourage you to use Apache or nginx installers, both -which perform the certificate management automatically. If, however, -you prefer to manage everything by hand, this section provides -information on where to find necessary files. - All generated keys and issued certificates can be found in ``/etc/letsencrypt/live/$domain``. Rather than copying, please point your (web) server configuration directly to those files (or create @@ -391,7 +367,7 @@ give us as much information as possible: also might contain personally identifiable information) - copy and paste ``certbot --version`` output - your operating system, including specific version -- specify which installation_ method you've chosen +- specify which installation method you've chosen Other methods of installation ============================= From 3ddd97235642a5db872018a17b911620cfb58971 Mon Sep 17 00:00:00 2001 From: Peter Eckersley Date: Fri, 13 May 2016 18:19:57 -0700 Subject: [PATCH 4/4] Update the renewal-related message we print after obtaining a cert --- certbot/main.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/certbot/main.py b/certbot/main.py index 0405d6eb5..66804143c 100644 --- a/certbot/main.py +++ b/certbot/main.py @@ -97,7 +97,7 @@ def _auth_from_domains(le_client, config, domains, lineage=None): hooks.post_hook(config) if not config.dry_run and not config.verb == "renew": - _report_new_cert(lineage.cert, lineage.fullchain) + _report_new_cert(config, lineage.cert, lineage.fullchain) return lineage, action @@ -267,7 +267,7 @@ def _find_domains(config, installer): return domains -def _report_new_cert(cert_path, fullchain_path): +def _report_new_cert(config, cert_path, fullchain_path): """Reports the creation of a new certificate to the user. :param str cert_path: path to cert @@ -285,12 +285,15 @@ def _report_new_cert(cert_path, fullchain_path): # Unless we're in .csr mode and there really isn't one and_chain = "has " path = cert_path + + verbswitch = ' with the "certonly" option' if config.verb == "run" else "" # XXX Perhaps one day we could detect the presence of known old webservers # and say something more informative here. - msg = ("Congratulations! Your certificate {0} been saved at {1}." - " Your cert will expire on {2}. To obtain a new version of the " - "certificate in the future, simply run Certbot again." - .format(and_chain, path, expiry)) + msg = ('Congratulations! Your certificate {0} been saved at {1}.' + ' Your cert will expire on {2}. To obtain a new or tweaked version of this ' + 'certificate in the future, simply run {3} again{4}. ' + 'To non-interactively renew *all* of your ceriticates, run "{3} renew"' + .format(and_chain, path, expiry, cli.cli_command, verbswitch)) reporter_util.add_message(msg, reporter_util.MEDIUM_PRIORITY) @@ -485,7 +488,7 @@ def _csr_obtain_cert(config, le_client): else: cert_path, _, cert_fullchain = le_client.save_certificate( certr, chain, config.cert_path, config.chain_path, config.fullchain_path) - _report_new_cert(cert_path, cert_fullchain) + _report_new_cert(config, cert_path, cert_fullchain) def obtain_cert(config, plugins, lineage=None):