# `certbot.main`

Certbot main entry point.

`certbot.main.``_suggest_donation_if_appropriate`(config)

  Potentially suggest a donation to support Certbot.

  Parameters: | config (interfaces.IConfig) – Configuration object
  Returns: | `None`
  Return type: | None

`certbot.main.``_report_successful_dry_run`(config)

  Reports on successful dry run

  Parameters: | config (interfaces.IConfig) – Configuration object
  Returns: | `None`
  Return type: | None

`certbot.main.``_get_and_save_cert`(le_client, config, domains=None, certname=None, lineage=None)

  Authenticate and enroll certificate.

  This method finds the relevant lineage, figures out what to do with it, then performs that action. Includes calls to hooks, various reports, checks, and requests for user input.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - domains (`list` of `str`) – List of domain names to get a certificate. Defaults to `None`
  - certname (str) – Name of new certificate. Defaults to `None`
  - lineage (storage.RenewableCert) – Certificate lineage object. Defaults to `None`

  Returns: | the issued certificate or `None` if doing a dry run
  Return type: | storage.RenewableCert or None
  Raises: | errors.Error – if certificate could not be obtained

`certbot.main.``_handle_subset_cert_request`(config, domains, cert)

  Figure out what to do if a previous cert had a subset of the names now requested

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - domains (`list` of `str`) – List of domain names
  - cert (storage.RenewableCert) – Certificate object

  Returns: | Tuple of (str action, cert_or_None) as per _find_lineage_for_domains_and_certname action can be: “newcert” | “renew” | “reinstall”
  Return type: | `tuple` of `str`

`certbot.main.``_handle_identical_cert_request`(config, lineage)

  Figure out what to do if a lineage has the same names as a previously obtained one

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - lineage (storage.RenewableCert) – Certificate lineage object

  Returns: | Tuple of (str action, cert_or_None) as per _find_lineage_for_domains_and_certname action can be: “newcert” | “renew” | “reinstall”
  Return type: | `tuple` of `str`

`certbot.main.``_find_lineage_for_domains`(config, domains)

  Determine whether there are duplicated names and how to handle them (renew, reinstall, newcert, or raising an error to stop the client run if the user chooses to cancel the operation when prompted).

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - domains (`list` of `str`) – List of domain names

  Returns: | Two-element tuple containing desired new-certificate behavior as a string token (“reinstall”, “renew”, or “newcert”), plus either a RenewableCert instance or `None` if renewal shouldn’t occur.
  Return type: | `tuple` of `str` and `storage.RenewableCert` or `None`
  Raises: | errors.Error – If the user would like to rerun the client again.

`certbot.main.``_find_cert`(config, domains, certname)

  Finds an existing certificate object given domains and/or a certificate name.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - domains (`list` of `str`) – List of domain names
  - certname (str) – Name of certificate

  Returns: | Two-element tuple of a boolean that indicates if this function should be followed by a call to fetch a certificate from the server, and either a RenewableCert instance or None.
  Return type: | `tuple` of `bool` and `storage.RenewableCert` or `None`

`certbot.main.``_find_lineage_for_domains_and_certname`(config, domains, certname)

  Find appropriate lineage based on given domains and/or certname.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - domains (`list` of `str`) – List of domain names
  - certname (str) – Name of certificate

  Returns: | Two-element tuple containing desired new-certificate behavior as a string token (“reinstall”, “renew”, or “newcert”), plus either a RenewableCert instance or None if renewal should not occur.
  Return type: | `tuple` of `str` and `storage.RenewableCert` or `None`
  Raises: | errors.Error – If the user would like to rerun the client again.

`certbot.main.``_get_added_removed`(after, before)

  Get lists of items removed from `before` and a lists of items added to `after`

`certbot.main.``_format_list`(character, strings)

  Format list with given character

`certbot.main.``_ask_user_to_confirm_new_names`(config, new_domains, certname, old_domains)

  Ask user to confirm update cert certname to contain new_domains.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - new_domains (`list` of `str`) – List of new domain names
  - certname (str) – Name of certificate
  - old_domains (`list` of `str`) – List of old domain names

  Returns: | None
  Return type: | None
  Raises: | errors.ConfigurationError – if cert name and domains mismatch

`certbot.main.``_find_domains_or_certname`(config, installer, question=None)

  Retrieve domains and certname from config or user input.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - installer (interfaces.IInstaller) – Installer object
  - question (str) – Overriding dialog question to ask the user if asked to choose from domain names.

  Returns: | Two-part tuple of domains and certname
  Return type: | `tuple` of list of `str` and `str`
  Raises: | errors.Error – Usage message, if parameters are not used correctly

`certbot.main.``_report_new_cert`(config, cert_path, fullchain_path, key_path=None)

  Reports the creation of a new certificate to the user.

  Parameters:

  - cert_path (str) – path to certificate
  - fullchain_path (str) – path to full chain
  - key_path (str) – path to private key, if available

  Returns: | `None`
  Return type: | None

`certbot.main.``_determine_account`(config)

  Determine which account to use.

  If `config.account` is `None`, it will be updated based on the user input. Same for `config.email`.

  Parameters: | config (interfaces.IConfig) – Configuration object
  Returns: | Account and optionally ACME client API (biproduct of new registration).
  Return type: | tuple of `certbot.account.Account` and `acme.client.Client`
  Raises: | errors.Error – If unable to register an account with ACME server

`certbot.main.``_delete_if_appropriate`(config)

  Does the user want to delete their now-revoked certs? If run in non-interactive mode, deleting happens automatically.

  Parameters: | config (interfaces.IConfig) – parsed command line arguments
  Returns: | `None`
  Return type: | None
  Raises: | errors.Error – If anything goes wrong, including bad user input, if an overlapping archive dir is found for the specified lineage, etc …

`certbot.main.``_init_le_client`(config, authenticator, installer)

  Initialize Let’s Encrypt Client

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - authenticator (interfaces.IAuthenticator) – Acme authentication handler
  - installer (interfaces.IInstaller) – Installer object

  Returns: | client: Client object
  Return type: | client.Client

`certbot.main.``unregister`(config, unused_plugins)

  Deactivate account on server

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``register`(config, unused_plugins)

  Create accounts on the server.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None` or a string indicating and error
  Return type: | None or str

`certbot.main.``update_account`(config, unused_plugins)

  Modify accounts on the server.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None` or a string indicating and error
  Return type: | None or str

`certbot.main.``_install_cert`(config, le_client, domains, lineage=None)

  Install a cert

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - le_client (client.Client) – Client object
  - domains (`list` of `str`) – List of domains
  - lineage (storage.RenewableCert) – Certificate lineage object. Defaults to `None`

  Returns: | `None`
  Return type: | None

`certbot.main.``install`(config, plugins)

  Install a previously obtained cert in a server.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None

`certbot.main.``_populate_from_certname`(config)

  Helper function for install to populate missing config values from lineage defined by –cert-name.

`certbot.main.``plugins_cmd`(config, plugins)

  List server software plugins.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None

`certbot.main.``enhance`(config, plugins)

  Add security enhancements to existing configuration

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None

`certbot.main.``rollback`(config, plugins)

  Rollback server configuration changes made during install.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None

`certbot.main.``config_changes`(config, unused_plugins)

  Show changes made to server config during installation

  View checkpoints and associated configuration changes.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``update_symlinks`(config, unused_plugins)

  Update the certificate file family symlinks

  Use the information in the config file to make symlinks point to the correct archive directory.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``rename`(config, unused_plugins)

  Rename a certificate

  Use the information in the config file to rename an existing lineage.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``delete`(config, unused_plugins)

  Delete a certificate

  Use the information in the config file to delete an existing lineage.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``certificates`(config, unused_plugins)

  Display information about certs configured with Certbot

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``revoke`(config, unused_plugins)

  Revoke a previously obtained certificate.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None` or string indicating error in case of error
  Return type: | None or str

`certbot.main.``run`(config, plugins)

  Obtain a certificate and install.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None

`certbot.main.``_csr_get_and_save_cert`(config, le_client)

  Obtain a cert using a user-supplied CSR

  This works differently in the CSR case (for now) because we don’t have the privkey, and therefore can’t construct the files for a lineage. So we just save the cert & chain to disk :/

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - client (client.Client) – Client object

  Returns: | `cert_path` and `fullchain_path` as absolute paths to the actual files
  Return type: | `tuple` of `str`

`certbot.main.``renew_cert`(config, plugins, lineage)

  Renew & save an existing cert. Do not install it.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins
  - lineage (storage.RenewableCert) – Certificate lineage object

  Returns: | `None`
  Return type: | None
  Raises: | errors.PluginSelectionError – MissingCommandlineFlag if supplied parameters do not pass

`certbot.main.``certonly`(config, plugins)

  Authenticate & obtain cert, but do not install it.

  This implements the ‘certonly’ subcommand.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - plugins (`list` of `str`) – List of plugins

  Returns: | `None`
  Return type: | None
  Raises: | errors.Error – If specified plugin could not be used

`certbot.main.``renew`(config, unused_plugins)

  Renew previously-obtained certificates.

  Parameters:

  - config (interfaces.IConfig) – Configuration object
  - unused_plugins (`list` of `str`) – List of plugins (deprecated)

  Returns: | `None`
  Return type: | None

`certbot.main.``make_or_verify_needed_dirs`(config)

  Create or verify existence of config, work, and hook directories.

  Parameters: | config (interfaces.IConfig) – Configuration object
  Returns: | `None`
  Return type: | None

`certbot.main.``set_displayer`(config)

  Set the displayer

  Parameters: | config (interfaces.IConfig) – Configuration object
  Returns: | `None`
  Return type: | None

`certbot.main.``main`(cli_args=None)

  Command line argument parsing and main script execution.

  Returns: | result of requested command

  Raises:

  - errors.Error – OS errors triggered by wrong permissions
  - errors.Error – error if plugin command is not supported