# `certbot_nginx.parser`

NginxParser is a member object of the NginxConfigurator class.

class `certbot_nginx.parser.``NginxParser`(root)

  Bases: `object`

  Class handles the fine details of parsing the Nginx Configuration.

  Variables:

  - root (str) – Normalized absolute path to the server root directory. Without trailing slash.
  - parsed (dict) – Mapping of file paths to parsed trees

  `load`()

    Loads Nginx files into a parsed tree.

  `_parse_recursively`(filepath)

    Parses nginx config files recursively by looking at ‘include’ directives inside ‘http’ and ‘server’ blocks. Note that this only reads Nginx files that potentially declare a virtual host.

    Parameters: | filepath (str) – The path to the files to parse, as a glob

  `abs_path`(path)

    Converts a relative path to an absolute path relative to the root. Does nothing for paths that are already absolute.

    Parameters: | path (str) – The path
    Returns: | The absolute path
    Return type: | str

  `_build_addr_to_ssl`()

    Builds a map from address to whether it listens on ssl in any server block

  `_get_raw_servers`()

    Get a map of unparsed all server blocks

  `get_vhosts`()

    Gets list of all ‘virtual hosts’ found in Nginx configuration. Technically this is a misnomer because Nginx does not have virtual hosts, it has ‘server blocks’.

    Returns: | List of `VirtualHost` objects found in configuration
    Return type: | list

  `_update_vhosts_addrs_ssl`(vhosts)

    Update a list of raw parsed vhosts to include global address sslishness

  `_get_included_directives`(block)

    Returns array with the “include” directives expanded out by concatenating the contents of the included file to the block.

    Parameters: | block (list) –
    Return type: | list

  `_parse_files`(filepath, override=False)

    Parse files from a glob

    Parameters:

    - filepath (str) – Nginx config file path
    - override (bool) – Whether to parse a file that has been parsed

    Returns: | list of parsed tree structures
    Return type: | list

  `_find_config_root`()

    Return the Nginx Configuration Root file.

  `filedump`(ext='tmp', lazy=True)

    Dumps parsed configurations into files.

    Parameters:

    - ext (str) – The file extension to use for the dumped files. If empty, this overrides the existing conf files.
    - lazy (bool) – Only write files that have been modified

  `parse_server`(server)

    Parses a list of server directives, accounting for global address sslishness.

    Parameters: | server (list) – list of directives in a server block
    Return type: | dict

  `has_ssl_on_directive`(vhost)

    Does vhost have ssl on for all ports?

    :param `VirtualHost` vhost: The vhost in question

    Returns: | True if ‘ssl on’ directive is included
    Return type: | bool

  `add_server_directives`(vhost, directives, insert_at_top=False)

    Add directives to the server block identified by vhost.

    This method modifies vhost to be fully consistent with the new directives.

    ..note :: It’s an error to try and add a nonrepeatable directive that already
      exists in the config block with a conflicting value.
    ..todo :: Doesn’t match server blocks whose server_name directives are
      split across multiple conf files.
    :param `VirtualHost` vhost: The vhost
      whose information we use to match on

    Parameters:

    - directives (list) – The directives to add
    - insert_at_top (bool) – True if the directives need to be inserted at the top of the server block instead of the bottom

  `update_or_add_server_directives`(vhost, directives, insert_at_top=False)

    Add or replace directives in the server block identified by vhost.

    This method modifies vhost to be fully consistent with the new directives.

    ..note :: When a directive with the same name already exists in the config block, the first instance will be replaced. Otherwise, the directive will be appended/prepended to the config block as in add_server_directives.

    ..todo :: Doesn’t match server blocks whose server_name directives are
      split across multiple conf files.
    :param `VirtualHost` vhost: The vhost
      whose information we use to match on

    Parameters:

    - directives (list) – The directives to add
    - insert_at_top (bool) – True if the directives need to be inserted at the top of the server block instead of the bottom

  `remove_server_directives`(vhost, directive_name, match_func=None)

    Remove all directives of type directive_name.

    :param `VirtualHost` vhost: The vhost
      to remove directives from

    Parameters:

    - directive_name (string) – The directive type to remove
    - match_func (callable) – Function of the directive that returns true for directives to be deleted.

  `duplicate_vhost`(vhost_template, remove_singleton_listen_params=False, only_directives=None)

    Duplicate the vhost in the configuration files.

    :param `VirtualHost` vhost_template: The vhost
      whose information we copy

    Parameters:

    - remove_singleton_listen_params (bool) – If we should remove parameters from listen directives in the block that can only be used once per address
    - only_directives (list) – If it exists, only duplicate the named directives. Only looks at first level of depth; does not expand includes.

    Returns: | A vhost object for the newly created vhost
    Return type: | `VirtualHost`

`certbot_nginx.parser.``_do_for_subarray`(entry, condition, func, path=None)

  Executes a function for a subarray of a nested array if it matches the given condition.

  Parameters:

  - entry (list) – The list to iterate over
  - condition (function) – Returns true iff func should be executed on item
  - func (function) – The function to call for each matching item

`certbot_nginx.parser.``get_best_match`(target_name, names)

  Finds the best match for target_name out of names using the Nginx name-matching rules (exact > longest wildcard starting with * > longest wildcard ending with * > regex).

  Parameters:

  - target_name (str) – The name to match
  - names (set) – The candidate server names

  Returns: | Tuple of (type of match, the name that matched)
  Return type: | tuple

`certbot_nginx.parser.``_is_include_directive`(entry)

  Checks if an nginx parsed entry is an ‘include’ directive.

  Parameters: | entry (list) – the parsed entry
  Returns: | Whether it’s an ‘include’ directive
  Return type: | bool

`certbot_nginx.parser.``_is_ssl_on_directive`(entry)

  Checks if an nginx parsed entry is an ‘ssl on’ directive.

  Parameters: | entry (list) – the parsed entry
  Returns: | Whether it’s an ‘ssl on’ directive
  Return type: | bool

`certbot_nginx.parser.``_add_directives`(directives, insert_at_top, block)

  Adds directives to a config block.

`certbot_nginx.parser.``_update_or_add_directives`(directives, insert_at_top, block)

  Adds or replaces directives in a config block.

`certbot_nginx.parser.``comment_directive`(block, location)

  Add a `#managed by Certbot` comment to the end of the line at location.

  Parameters:

  - block (list) – The block containing the directive to be commented
  - location (int) – The location within `block` of the directive to be commented

`certbot_nginx.parser.``_comment_out_directive`(block, location, include_location)

  Comment out the line at location, with a note of explanation.

`certbot_nginx.parser.``_find_location`(block, directive_name, match_func=None)

  Finds the index of the first instance of directive_name in block. If no line exists, use None.

`certbot_nginx.parser.``_is_whitespace_or_comment`(directive)

  Is this directive either a whitespace or comment directive?

`certbot_nginx.parser.``_remove_directives`(directive_name, match_func, block)

  Removes directives of name directive_name from a config block if match_func matches.

`certbot_nginx.parser.``_apply_global_addr_ssl`(addr_to_ssl, parsed_server)

  Apply global sslishness information to the parsed server block

`certbot_nginx.parser.``_parse_server_raw`(server)

  Parses a list of server directives.

  Parameters: | server (list) – list of directives in a server block
  Return type: | dict