Coverage for nova/conf/spice.py: 82%
11 statements
« prev ^ index » next coverage.py v7.6.12, created at 2025-04-17 15:08 +0000
1# Copyright 2016 OpenStack Foundation
2# All Rights Reserved.
3#
4# Licensed under the Apache License, Version 2.0 (the "License"); you may
5# not use this file except in compliance with the License. You may obtain
6# a copy of the License at
7#
8# http://www.apache.org/licenses/LICENSE-2.0
9#
10# Unless required by applicable law or agreed to in writing, software
11# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
12# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
13# License for the specific language governing permissions and limitations
14# under the License.
16from oslo_config import cfg
18spice_opt_group = cfg.OptGroup('spice',
19 title="SPICE console features",
20 help="""
21SPICE console feature allows you to connect to a guest virtual machine.
22SPICE is a replacement for fairly limited VNC protocol.
24Following requirements must be met in order to use SPICE:
26* Virtualization driver must be libvirt
27* spice.enabled set to True
28* vnc.enabled set to False
29* update html5proxy_base_url
30* update server_proxyclient_address
31""")
33CLI_OPTS = [
34 cfg.HostAddressOpt('html5proxy_host',
35 default='0.0.0.0',
36 help="""
37IP address or a hostname on which the ``nova-spicehtml5proxy`` service
38listens for incoming requests.
40Related options:
42* This option depends on the ``html5proxy_base_url`` option.
43 The ``nova-spicehtml5proxy`` service must be listening on a host that is
44 accessible from the HTML5 client.
45"""),
46 cfg.PortOpt('html5proxy_port',
47 default=6082,
48 help="""
49Port on which the ``nova-spicehtml5proxy`` service listens for incoming
50requests.
52Related options:
54* This option depends on the ``html5proxy_base_url`` option.
55 The ``nova-spicehtml5proxy`` service must be listening on a port that is
56 accessible from the HTML5 client.
57""")
58]
60ALL_OPTS = [
61 cfg.BoolOpt('enabled',
62 default=False,
63 help="""
64Enable SPICE related features.
66Related options:
68* VNC must be explicitly disabled to get access to the SPICE console. Set the
69 enabled option to False in the [vnc] section to disable the VNC console.
70"""),
71 cfg.BoolOpt('agent_enabled',
72 default=True,
73 help="""
74Enable the SPICE guest agent support on the instances.
76The Spice agent works with the Spice protocol to offer a better guest console
77experience. However, the Spice console can still be used without the Spice
78Agent. With the Spice agent installed the following features are enabled:
80* Copy & Paste of text and images between the guest and client machine
81* Automatic adjustment of resolution when the client screen changes - e.g.
82 if you make the Spice console full screen the guest resolution will adjust to
83 match it rather than letterboxing.
84* Better mouse integration - The mouse can be captured and released without
85 needing to click inside the console or press keys to release it. The
86 performance of mouse movement is also improved.
87"""),
88 cfg.StrOpt('image_compression',
89 advanced=True,
90 choices=[
91 ('auto_glz', 'enable image compression mode to choose between glz '
92 'and quic algorithm, based on image properties'),
93 ('auto_lz', 'enable image compression mode to choose between lz '
94 'and quic algorithm, based on image properties'),
95 ('quic', 'enable image compression based on the SFALIC algorithm'),
96 ('glz', 'enable image compression using lz with history based '
97 'global dictionary'),
98 ('lz', 'enable image compression with the Lempel-Ziv algorithm'),
99 ('off', 'disable image compression')
100 ],
101 help="""
102Configure the SPICE image compression (lossless).
103"""),
104 cfg.StrOpt('jpeg_compression',
105 advanced=True,
106 choices=[
107 ('auto', 'enable JPEG image compression automatically'),
108 ('never', 'disable JPEG image compression'),
109 ('always', 'enable JPEG image compression')
110 ],
111 help="""
112Configure the SPICE wan image compression (lossy for slow links).
113"""),
114 cfg.StrOpt('zlib_compression',
115 advanced=True,
116 choices=[
117 ('auto', 'enable zlib image compression automatically'),
118 ('never', 'disable zlib image compression'),
119 ('always', 'enable zlib image compression')
120 ],
121 help="""
122Configure the SPICE wan image compression (lossless for slow links).
123"""),
124 cfg.BoolOpt('playback_compression',
125 advanced=True,
126 help="""
127Enable the SPICE audio stream compression (using celt).
128"""),
129 cfg.StrOpt('streaming_mode',
130 advanced=True,
131 choices=[
132 ('filter', 'SPICE server adds additional filters to decide if '
133 'video streaming should be activated'),
134 ('all', 'any fast-refreshing window can be encoded into a video '
135 'stream'),
136 ('off', 'no video detection and (lossy) compression is performed')
137 ],
138 help="""
139Configure the SPICE video stream detection and (lossy) compression.
140"""),
141 cfg.URIOpt('html5proxy_base_url',
142 default='http://127.0.0.1:6082/spice_auto.html',
143 help="""
144Location of the SPICE HTML5 console proxy.
146End user would use this URL to connect to the `nova-spicehtml5proxy``
147service. This service will forward request to the console of an instance.
149In order to use SPICE console, the service ``nova-spicehtml5proxy`` should be
150running. This service is typically launched on the controller node.
152Possible values:
154* Must be a valid URL of the form: ``http://host:port/spice_auto.html``
155 where host is the node running ``nova-spicehtml5proxy`` and the port is
156 typically 6082. Consider not using default value as it is not well defined
157 for any real deployment.
159Related options:
161* This option depends on ``html5proxy_host`` and ``html5proxy_port`` options.
162 The access URL returned by the compute node must have the host
163 and port where the ``nova-spicehtml5proxy`` service is listening.
164"""),
165 cfg.URIOpt('spice_direct_proxy_base_url',
166 default='http://127.0.0.1:13002/nova',
167 help="""
168Location of a SPICE protocol native console proxy.
170A user can retrieve a virt-viewer style .vv connection configuration file by
171accessing this URL with the attached token when a console is created.
173Possible values:
175* Must be a valid URL of the form: ``http://host:port/nova`` where host is the
176 node running the SPICE protocol native proxy and the port is typically 13002.
177 Note that the port component is optional if you are using the default port
178 for HTTP or HTTPS. Consider not using the default value as it is not well
179 defined for any real deployment.
180"""),
181 cfg.StrOpt('server_listen',
182 default='127.0.0.1',
183 help="""
184The address where the SPICE server running on the instances should listen.
186Typically, the ``nova-spicehtml5proxy`` proxy client runs on the controller
187node and connects over the private network to this address on the compute
188node(s).
190Possible values:
192* IP address to listen on.
193"""),
194 cfg.StrOpt('server_proxyclient_address',
195 default='127.0.0.1',
196 help="""
197The address used by ``nova-spicehtml5proxy`` client to connect to instance
198console.
200Typically, the ``nova-spicehtml5proxy`` proxy client runs on the
201controller node and connects over the private network to this address on the
202compute node(s).
204Possible values:
206* Any valid IP address on the compute node.
208Related options:
210* This option depends on the ``server_listen`` option.
211 The proxy client must be able to access the address specified in
212 ``server_listen`` using the value of this option.
213"""),
214 cfg.BoolOpt('require_secure',
215 default=False,
216 help="""
217Whether to require secure TLS connections to SPICE consoles.
219If you're providing direct access to SPICE consoles instead of using the HTML5
220proxy, you may wish those connections to be encrypted. If so, set this value to
221True.
223Note that use of secure consoles requires that you setup TLS certificates on
224each hypervisor.
226Possible values:
228* False: console traffic is not encrypted.
229* True: console traffic is required to be protected by TLS.
230"""),
231]
233ALL_OPTS.extend(CLI_OPTS)
236def register_opts(conf):
237 conf.register_opts(ALL_OPTS, group=spice_opt_group)
240def register_cli_opts(conf):
241 conf.register_cli_opts(CLI_OPTS, group=spice_opt_group)
244def list_opts():
245 return {spice_opt_group: ALL_OPTS}