# `certbot.hooks`

Facilities for implementing hooks that call shell commands.

`certbot.hooks.``validate_hooks`(config)

  Check hook commands are executable.

`certbot.hooks.``_prog`(shell_cmd)

  Extract the program run by a shell command.

  Parameters: | shell_cmd (str) – command to be executed
  Returns: | basename of command or None if the command isn’t found
  Return type: | str or None

`certbot.hooks.``validate_hook`(shell_cmd, hook_name)

  Check that a command provided as a hook is plausibly executable.

  Raises: | .errors.HookCommandNotFound – if the command is not found

`certbot.hooks.``pre_hook`(config)

  Run pre-hooks if they exist and haven’t already been run.

  When Certbot is running with the renew subcommand, this function runs any hooks found in the config.renewal_pre_hooks_dir (if they have not already been run) followed by any pre-hook in the config. If hooks in config.renewal_pre_hooks_dir are run and the pre-hook in the config is a path to one of these scripts, it is not run twice.

  Parameters: | config (configuration.NamespaceConfig) – Certbot settings

`certbot.hooks.``_run_pre_hook_if_necessary`(command)

  Run the specified pre-hook if we haven’t already.

  If we’ve already run this exact command before, a message is logged saying the pre-hook was skipped.

  Parameters: | command (str) – pre-hook to be run

`certbot.hooks.``post_hook`(config)

  Run post-hooks if defined.

  This function also registers any executables found in config.renewal_post_hooks_dir to be run when Certbot is used with the renew subcommand.

  If the verb is renew, we delay executing any post-hooks until `run_saved_post_hooks()` is called. In this case, this function registers all hooks found in config.renewal_post_hooks_dir to be called followed by any post-hook in the config. If the post-hook in the config is a path to an executable in the post-hook directory, it is not scheduled to be run twice.

  Parameters: | config (configuration.NamespaceConfig) – Certbot settings

`certbot.hooks.``_run_eventually`(command)

  Registers a post-hook to be run eventually.

  All commands given to this function will be run exactly once in the order they were given when `run_saved_post_hooks()` is called.

  Parameters: | command (str) – post-hook to register to be run

`certbot.hooks.``run_saved_post_hooks`()

  Run any post hooks that were saved up in the course of the ‘renew’ verb

`certbot.hooks.``deploy_hook`(config, domains, lineage_path)

  Run post-issuance hook if defined.

  Parameters:

  - config (configuration.NamespaceConfig) – Certbot settings
  - domains (`list` of `str`) – domains in the obtained certificate
  - lineage_path (str) – live directory path for the new cert

`certbot.hooks.``renew_hook`(config, domains, lineage_path)

  Run post-renewal hooks.

  This function runs any hooks found in config.renewal_deploy_hooks_dir followed by any renew-hook in the config. If the renew-hook in the config is a path to a script in config.renewal_deploy_hooks_dir, it is not run twice.

  If Certbot is doing a dry run, no hooks are run and messages are logged saying that they were skipped.

  Parameters:

  - config (configuration.NamespaceConfig) – Certbot settings
  - domains (`list` of `str`) – domains in the obtained certificate
  - lineage_path (str) – live directory path for the new cert

`certbot.hooks.``_run_deploy_hook`(command, domains, lineage_path, dry_run)

  Run the specified deploy-hook (if not doing a dry run).

  If dry_run is True, command is not run and a message is logged saying that it was skipped. If dry_run is False, the hook is run after setting the appropriate environment variables.

  Parameters:

  - command (str) – command to run as a deploy-hook
  - domains (`list` of `str`) – domains in the obtained certificate
  - lineage_path (str) – live directory path for the new cert
  - dry_run (bool) – True iff Certbot is doing a dry run

`certbot.hooks.``_run_hook`(shell_cmd)

  Run a hook command.

  Returns: | stderr if there was any

`certbot.hooks.``execute`(shell_cmd)

  Run a command.

  Returns: | `tuple` (`str` stderr, `str` stdout)

`certbot.hooks.``list_hooks`(dir_path)

  List paths to all hooks found in dir_path in sorted order.

  Parameters: | dir_path (str) – directory to search
  Returns: | `list` of `str`
  Return type: | sorted list of absolute paths to executables in dir_path