From d289d0d17b4e2ace80c74be80d768a3820a9da62 Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Mon, 19 Feb 2018 21:55:16 -0500 Subject: [PATCH] Revise help text for uri filtering options Clarify the help text and clean up some log messages. Includes the regenerated glance-image-import.conf.sample file. Change-Id: I7f9087aaf9c6969e15f63029cc38fe5a0939ad40 Closes-bug: #1749788 --- etc/glance-image-import.conf.sample | 118 +++++++++--------- glance/api/v2/images.py | 2 +- .../async/flows/_internal_plugins/__init__.py | 118 +++++++++--------- glance/common/utils.py | 6 +- 4 files changed, 124 insertions(+), 120 deletions(-) diff --git a/etc/glance-image-import.conf.sample b/etc/glance-image-import.conf.sample index c70ccbc091..f1b7f63554 100644 --- a/etc/glance-image-import.conf.sample +++ b/etc/glance-image-import.conf.sample @@ -39,19 +39,21 @@ # # -# Specify the allowed url schemes for web-download. +# Specify the "whitelist" of allowed url schemes for web-download. # -# This option provides whitelisting for uri schemes that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting of the schemes but obeys host and port filtering. +# This option provides whitelisting of uri schemes that will be allowed when +# an end user imports an image using the web-download import method. The +# whitelist has priority such that if there is also a blacklist defined for +# schemes, the blacklist will be ignored. Host and port filtering, however, +# will be applied. # -# For example: If scheme blacklisting contains 'http' and whitelist contains -# ['http', 'https'] the whitelist is obeyed on http://example.com but any -# other scheme like ftp://example.com is blocked even it's not blacklisted. +# See the Glance Administration Guide for more information. # # Possible values: # * List containing normalized url schemes as they are returned from -# urllib.parse. For example ['ftp','https'] +# urllib.parse. For example ['ftp','https'] +# * Hint: leave the whitelist empty if you want the disallowed_schemes +# blacklist to be processed # # Related options: # * disallowed_schemes @@ -64,21 +66,19 @@ #allowed_schemes = http,https # -# Specify the blacklisted url schemes for web-download. +# Specify the "blacklist" of uri schemes disallowed for web-download. # -# This option provides blacklisting for uri schemes that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting of the schemes but obeys host and port filtering. Blacklisting -# can be used to prevent specific scheme to be used when whitelisting is not -# in use. +# This option provides blacklisting of uri schemes that will be rejected when +# an end user imports an image using the web-download import method. Note +# that if a scheme whitelist is defined using the 'allowed_schemes' option, +# *this option will be ignored*. Host and port filtering, however, will be +# applied. # -# For example: If scheme blacklisting contains 'http' and whitelist contains -# ['http', 'https'] the whitelist is obeyed on http://example.com but any -# other scheme like ftp://example.com is blocked even it's not blacklisted. +# See the Glance Administration Guide for more information. # # Possible values: # * List containing normalized url schemes as they are returned from -# urllib.parse. For example ['ftp','https'] +# urllib.parse. For example ['ftp','https'] # * By default the list is empty # # Related options: @@ -92,23 +92,23 @@ #disallowed_schemes = # -# Specify the allowed target hosts for web-download. +# Specify the "whitelist" of allowed target hosts for web-download. # -# This option provides whitelisting for hosts that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting of the hosts but obeys scheme and port filtering. +# This option provides whitelisting of hosts that will be allowed when an end +# user imports an image using the web-download import method. The whitelist +# has priority such that if there is also a blacklist defined for hosts, the +# blacklist will be ignored. The uri must have already passed scheme +# filtering before this host filter will be applied. If the uri passes, port +# filtering will then be applied. # -# For example: If scheme blacklisting contains 'http' and whitelist contains -# ['http', 'https'] the whitelist is obeyed on http://example.com but any -# other scheme like ftp://example.com is blocked even it's not blacklisted. -# Same way the whitelisted example.com is only obeyed on the allowed schemes -# and or ports. Whitelisting of the host does not allow all schemes and ports -# accessed. +# See the Glance Administration Guide for more information. # # Possible values: # * List containing normalized hostname or ip like it would be returned -# in the urllib.parse netloc without the port +# in the urllib.parse netloc without the port # * By default the list is empty +# * Hint: leave the whitelist empty if you want the disallowed_hosts +# blacklist to be processed # # Related options: # * allowed_schemes @@ -121,21 +121,21 @@ #allowed_hosts = # -# Specify the blacklisted hosts for web-download. +# Specify the "blacklist" of hosts disallowed for web-download. # -# This option provides blacklisting for hosts that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting but obeys scheme and port filtering. +# This option provides blacklisting of hosts that will be rejected when an end +# user imports an image using the web-download import method. Note that if a +# host whitelist is defined using the 'allowed_hosts' option, *this option +# will be ignored*. # -# For example: If scheme blacklisting contains 'http' and whitelist contains -# ['http', 'https'] the whitelist is obeyed on http://example.com but any -# other scheme like ftp://example.com is blocked even it's not blacklisted. -# The blacklisted example.com is obeyed on any url pointing to that host -# regardless of what their scheme or port is. +# The uri must have already passed scheme filtering before this host filter +# will be applied. If the uri passes, port filtering will then be applied. +# +# See the Glance Administration Guide for more information. # # Possible values: # * List containing normalized hostname or ip like it would be returned -# in the urllib.parse netloc without the port +# in the urllib.parse netloc without the port # * By default the list is empty # # Related options: @@ -149,19 +149,22 @@ #disallowed_hosts = # -# Specify the allowed ports for web-download. +# Specify the "whitelist" of allowed ports for web-download. # -# This option provides whitelisting for uri ports that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting of the ports but obeys host and scheme filtering. +# This option provides whitelisting of ports that will be allowed when an end +# user imports an image using the web-download import method. The whitelist +# has priority such that if there is also a blacklist defined for ports, the +# blacklist will be ignored. Note that scheme and host filtering have already +# been applied by the time a uri hits the port filter. # -# For example: If scheme blacklisting contains '80' and whitelist contains -# ['80', '443'] the whitelist is obeyed on http://example.com:80 but any -# other port like ftp://example.com:21 is blocked even it's not blacklisted. +# See the Glance Administration Guide for more information. # # Possible values: # * List containing ports as they are returned from urllib.parse netloc -# field. For example ['80','443'] +# field. Thus the value is a list of integer values, for example +# [80, 443] +# * Hint: leave the whitelist empty if you want the disallowed_ports +# blacklist to be processed # # Related options: # * allowed_schemes @@ -173,22 +176,21 @@ #allowed_ports = 80,443 # -# Specify the disallowed ports for web-download. +# Specify the "blacklist" of disallowed ports for web-download. # -# This option provides blacklisting for uri ports that web-download import -# method will be using. Whitelisting is always priority and ignores any -# blacklisting of the ports but obeys host and scheme filtering. +# This option provides blacklisting of target ports that will be rejected when +# an end user imports an image using the web-download import method. Note +# that if a port whitelist is defined using the 'allowed_ports' option, *this +# option will be ignored*. Note that scheme and host filtering have already +# been applied by the time a uri hits the port filter. # -# For example: If scheme blacklisting contains '80' and whitelist contains -# ['80', '443'] the whitelist is obeyed on http://example.com:80 but any -# other port like ftp://example.com:21 is blocked even it's not blacklisted. -# If no whitelisting is defined any scheme and host combination is disallowed -# for the blacklisted port. +# See the Glance Administration Guide for more information. # # Possible values: # * List containing ports as they are returned from urllib.parse netloc -# field. For example ['80','443'] -# * By default this list is empty. +# field. Thus the value is a list of integer values, for example +# [22, 88] +# * By default this list is empty # # Related options: # * allowed_schemes diff --git a/glance/api/v2/images.py b/glance/api/v2/images.py index 765ade36a7..bfd8fd76f3 100644 --- a/glance/api/v2/images.py +++ b/glance/api/v2/images.py @@ -101,7 +101,7 @@ class ImagesController(object): uri = body.get('method').get('uri') if (import_method == 'web-download' and not utils.validate_import_uri(uri)): - LOG.debug("URI for web-download does not pass filtering: %s" % + LOG.debug("URI for web-download does not pass filtering: %s", uri) msg = (_("URI for web-download does not pass filtering: %s") % uri) diff --git a/glance/async/flows/_internal_plugins/__init__.py b/glance/async/flows/_internal_plugins/__init__.py index f584304262..9efada3892 100644 --- a/glance/async/flows/_internal_plugins/__init__.py +++ b/glance/async/flows/_internal_plugins/__init__.py @@ -28,19 +28,21 @@ import_filtering_opts = [ bounds=True, default=['http', 'https'], help=_(""" -Specify the allowed url schemes for web-download. +Specify the "whitelist" of allowed url schemes for web-download. -This option provides whitelisting for uri schemes that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting of the schemes but obeys host and port filtering. +This option provides whitelisting of uri schemes that will be allowed when +an end user imports an image using the web-download import method. The +whitelist has priority such that if there is also a blacklist defined for +schemes, the blacklist will be ignored. Host and port filtering, however, +will be applied. -For example: If scheme blacklisting contains 'http' and whitelist contains -['http', 'https'] the whitelist is obeyed on http://example.com but any -other scheme like ftp://example.com is blocked even it's not blacklisted. +See the Glance Administration Guide for more information. Possible values: * List containing normalized url schemes as they are returned from - urllib.parse. For example ['ftp','https'] + urllib.parse. For example ['ftp','https'] + * Hint: leave the whitelist empty if you want the disallowed_schemes + blacklist to be processed Related options: * disallowed_schemes @@ -55,21 +57,19 @@ Related options: bounds=True, default=[], help=_(""" -Specify the blacklisted url schemes for web-download. +Specify the "blacklist" of uri schemes disallowed for web-download. -This option provides blacklisting for uri schemes that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting of the schemes but obeys host and port filtering. Blacklisting -can be used to prevent specific scheme to be used when whitelisting is not -in use. +This option provides blacklisting of uri schemes that will be rejected when +an end user imports an image using the web-download import method. Note +that if a scheme whitelist is defined using the 'allowed_schemes' option, +*this option will be ignored*. Host and port filtering, however, will be +applied. -For example: If scheme blacklisting contains 'http' and whitelist contains -['http', 'https'] the whitelist is obeyed on http://example.com but any -other scheme like ftp://example.com is blocked even it's not blacklisted. +See the Glance Administration Guide for more information. Possible values: * List containing normalized url schemes as they are returned from - urllib.parse. For example ['ftp','https'] + urllib.parse. For example ['ftp','https'] * By default the list is empty Related options: @@ -85,23 +85,23 @@ Related options: bounds=True, default=[], help=_(""" -Specify the allowed target hosts for web-download. +Specify the "whitelist" of allowed target hosts for web-download. -This option provides whitelisting for hosts that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting of the hosts but obeys scheme and port filtering. +This option provides whitelisting of hosts that will be allowed when an end +user imports an image using the web-download import method. The whitelist +has priority such that if there is also a blacklist defined for hosts, the +blacklist will be ignored. The uri must have already passed scheme +filtering before this host filter will be applied. If the uri passes, port +filtering will then be applied. -For example: If scheme blacklisting contains 'http' and whitelist contains -['http', 'https'] the whitelist is obeyed on http://example.com but any -other scheme like ftp://example.com is blocked even it's not blacklisted. -Same way the whitelisted example.com is only obeyed on the allowed schemes -and or ports. Whitelisting of the host does not allow all schemes and ports -accessed. +See the Glance Administration Guide for more information. Possible values: * List containing normalized hostname or ip like it would be returned - in the urllib.parse netloc without the port + in the urllib.parse netloc without the port * By default the list is empty + * Hint: leave the whitelist empty if you want the disallowed_hosts + blacklist to be processed Related options: * allowed_schemes @@ -116,21 +116,21 @@ Related options: bounds=True, default=[], help=_(""" -Specify the blacklisted hosts for web-download. +Specify the "blacklist" of hosts disallowed for web-download. -This option provides blacklisting for hosts that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting but obeys scheme and port filtering. +This option provides blacklisting of hosts that will be rejected when an end +user imports an image using the web-download import method. Note that if a +host whitelist is defined using the 'allowed_hosts' option, *this option +will be ignored*. -For example: If scheme blacklisting contains 'http' and whitelist contains -['http', 'https'] the whitelist is obeyed on http://example.com but any -other scheme like ftp://example.com is blocked even it's not blacklisted. -The blacklisted example.com is obeyed on any url pointing to that host -regardless of what their scheme or port is. +The uri must have already passed scheme filtering before this host filter +will be applied. If the uri passes, port filtering will then be applied. + +See the Glance Administration Guide for more information. Possible values: * List containing normalized hostname or ip like it would be returned - in the urllib.parse netloc without the port + in the urllib.parse netloc without the port * By default the list is empty Related options: @@ -146,19 +146,22 @@ Related options: bounds=True, default=[80, 443], help=_(""" -Specify the allowed ports for web-download. +Specify the "whitelist" of allowed ports for web-download. -This option provides whitelisting for uri ports that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting of the ports but obeys host and scheme filtering. +This option provides whitelisting of ports that will be allowed when an end +user imports an image using the web-download import method. The whitelist +has priority such that if there is also a blacklist defined for ports, the +blacklist will be ignored. Note that scheme and host filtering have already +been applied by the time a uri hits the port filter. -For example: If scheme blacklisting contains '80' and whitelist contains -['80', '443'] the whitelist is obeyed on http://example.com:80 but any -other port like ftp://example.com:21 is blocked even it's not blacklisted. +See the Glance Administration Guide for more information. Possible values: * List containing ports as they are returned from urllib.parse netloc - field. For example ['80','443'] + field. Thus the value is a list of integer values, for example + [80, 443] + * Hint: leave the whitelist empty if you want the disallowed_ports + blacklist to be processed Related options: * allowed_schemes @@ -172,22 +175,21 @@ Related options: bounds=True, default=[], help=_(""" -Specify the disallowed ports for web-download. +Specify the "blacklist" of disallowed ports for web-download. -This option provides blacklisting for uri ports that web-download import -method will be using. Whitelisting is always priority and ignores any -blacklisting of the ports but obeys host and scheme filtering. +This option provides blacklisting of target ports that will be rejected when +an end user imports an image using the web-download import method. Note +that if a port whitelist is defined using the 'allowed_ports' option, *this +option will be ignored*. Note that scheme and host filtering have already +been applied by the time a uri hits the port filter. -For example: If scheme blacklisting contains '80' and whitelist contains -['80', '443'] the whitelist is obeyed on http://example.com:80 but any -other port like ftp://example.com:21 is blocked even it's not blacklisted. -If no whitelisting is defined any scheme and host combination is disallowed -for the blacklisted port. +See the Glance Administration Guide for more information. Possible values: * List containing ports as they are returned from urllib.parse netloc - field. For example ['80','443'] - * By default this list is empty. + field. Thus the value is a list of integer values, for example + [22, 88] + * By default this list is empty Related options: * allowed_schemes diff --git a/glance/common/utils.py b/glance/common/utils.py index 876afa44f1..3dbc2160b0 100644 --- a/glance/common/utils.py +++ b/glance/common/utils.py @@ -154,15 +154,15 @@ def validate_import_uri(uri): # logging it to inform only allowed will be obeyed. if wl_schemes and bl_schemes: bl_schemes = [] - LOG.debug("Both allowed and disallowed schemes has been configured." + LOG.debug("Both allowed and disallowed schemes has been configured. " "Will only process allowed list.") if wl_hosts and bl_hosts: bl_hosts = [] - LOG.debug("Both allowed and disallowed hosts has been configured." + LOG.debug("Both allowed and disallowed hosts has been configured. " "Will only process allowed list.") if wl_ports and bl_ports: bl_ports = [] - LOG.debug("Both allowed and disallowed ports has been configured." + LOG.debug("Both allowed and disallowed ports has been configured. " "Will only process allowed list.") if not scheme or ((wl_schemes and scheme not in wl_schemes) or