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