Update tobiko.conf documentation page

- add autogenerated tobiko.conf.sample file to the repo
- add links to the tobiko.conf.sample to tobiko.conf locations
- sligthly simplify documentation structure

Change-Id: I4d239798bef931460c63ed69ad1b94d6c8807e83
This commit is contained in:
Federico Ressi 2022-01-21 11:13:39 +01:00
parent 4607ac648f
commit b56811af76
17 changed files with 612 additions and 373 deletions

6
.gitignore vendored
View File

@ -26,7 +26,6 @@ ChangeLog
doc/build/* doc/build/*
cover/ cover/
dist/ dist/
etc/*.sample
report/ report/
test_results* test_results*
zuul/versioninfo zuul/versioninfo
@ -34,16 +33,13 @@ zuul/versioninfo
# Files created by releasenotes build # Files created by releasenotes build
releasenotes/build releasenotes/build
# Docs related files
doc/source/_static/config-samples/*.sample
Pipfile.lock Pipfile.lock
# Tobiko configuration file # Tobiko configuration file
clouds.yaml clouds.yaml
ssh_config ssh_config
ssh_id* ssh_id*
tobiko.conf* tobiko.conf
# Infrared things # Infrared things
.infrared .infrared

View File

@ -0,0 +1,545 @@
[DEFAULT]
[centos]
#
# From tobiko
#
# Default centos image name (string value)
#image_name = <None>
# Default centos image URL (string value)
#image_url = <None>
# Default centos image filename (string value)
#image_file = <None>
# Default centos container format (string value)
#container_format = <None>
# Default centos disk format (string value)
#disk_format = <None>
# Default centos username (string value)
#username = <None>
# Default centos password (string value)
#password = <None>
# Default centos SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>
[centos7]
#
# From tobiko
#
# Default centos7 image name (string value)
#image_name = <None>
# Default centos7 image URL (string value)
#image_url = <None>
# Default centos7 image filename (string value)
#image_file = <None>
# Default centos7 container format (string value)
#container_format = <None>
# Default centos7 disk format (string value)
#disk_format = <None>
# Default centos7 username (string value)
#username = <None>
# Default centos7 password (string value)
#password = <None>
# Default centos7 SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>
[cirros]
#
# From tobiko
#
# Default cirros image name (string value)
#image_name = <None>
# Default cirros image URL (string value)
#image_url = <None>
# Default cirros image filename (string value)
#image_file = <None>
# Default cirros container format (string value)
#container_format = <None>
# Default cirros disk format (string value)
#disk_format = <None>
# Default cirros username (string value)
#username = <None>
# Default cirros password (string value)
#password = <None>
# Default cirros SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>
[fedora]
#
# From tobiko
#
# Default fedora image name (string value)
#image_name = <None>
# Default fedora image URL (string value)
#image_url = <None>
# Default fedora image filename (string value)
#image_file = <None>
# Default fedora container format (string value)
#container_format = <None>
# Default fedora disk format (string value)
#disk_format = <None>
# Default fedora username (string value)
#username = <None>
# Default fedora password (string value)
#password = <None>
# Default fedora SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>
[glance]
#
# From tobiko
#
# Default directory where to look for image files (string value)
#image_dir = ~/.tobiko/cache/glance/images
[http]
#
# From tobiko
#
# HTTP proxy URL for Rest APIs (string value)
#http_proxy = <None>
# HTTPS proxy URL for Rest APIs (string value)
#https_proxy = <None>
# Don't use proxy server to connect to listed hosts (string value)
#no_proxy = <None>
[iperf3]
#
# From tobiko
#
# Port number (integer value)
#port = <None>
# tcp and udp values are supported (string value)
# Possible values:
# tcp - <No description provided>
# udp - <No description provided>
#protocol = <None>
# target bit rate (integer value)
#bitrate = 20000000
# direction download (True) or upload (False) (boolean value)
#download = <None>
# timeout of the iperf test (integer value)
#timeout = 10
[keystone]
#
# From tobiko
#
# Identity API version (integer value)
#api_version = <None>
# Identity service URL (string value)
#auth_url = <None>
# Username (string value)
#username = <None>
# Project name (string value)
#project_name = <None>
# Password (string value)
#password = <None>
# Domain name (string value)
#domain_name = <None>
# User domain name (string value)
#user_domain_name = <None>
# Project domain name (string value)
#project_domain_name = <None>
# Project domain ID (string value)
#project_domain_id = <None>
# Trust ID for trust scoping. (string value)
#trust_id = <None>
# Cloud name used pick authentication parameters from clouds.* (string value)
#cloud_name = <None>
# Directories where to look for clouds files (list value)
#clouds_file_dirs = .,~/.config/openstack,/etc/openstack
# Clouds file names (list value)
#clouds_file_names = clouds.yaml,clouds.yml,clouds.json
[neutron]
#
# From tobiko
#
# Network for creating ports on an external network (string value)
#external_network = <None>
# Network for creating floating IPs (string value)
#floating_network = <None>
# The CIDR block to allocate IPv4 subnets from (string value)
#ipv4_cidr = 10.100.0.0/16
# The mask bits for IPv4 subnets (integer value)
#ipv4_prefixlen = 24
# List of nameservers IPv4 addresses (list value)
#ipv4_dns_nameservers = <None>
# The CIDR block to allocate IPv6 subnets from (string value)
#ipv6_cidr = 2001:db8::/48
# The mask bits for IPv6 subnets (integer value)
#ipv6_prefixlen = 64
# List of nameservers IPv6 addresses (list value)
#ipv6_dns_nameservers = <None>
# Customized maximum transfer unit size
# Notes:
# - MTU values as small as 1000 has been seen breaking networking binding due to an
# unknown cause.
# - Too big MTU values (like greater than 1400) may be refused during network creation
# (integer value)
#custom_mtu_size = 1350
# Host where nameservers files are located (string value)
#nameservers_host = <None>
# File to parse for getting default nameservers list (list value)
#nameservers_filenames = /etc/resolv.conf
# The BW limit value configured for the QoS Policy Rule (integer value)
#bwlimit_kbps = 1000
# The direction for the QoS Policy Rule (string value)
#direction = egress
# The DSCP marking value for the QoS Policy Rule (integer value)
#dscp_mark = 40
# VLAN trunk subport segmentation ID (integer value)
#vlan_id = 101
# Behave as these networking extensions are not available (list value)
#ignore_extensions =
[nova]
#
# From tobiko
#
# Default SSH key to login to server instances (string value)
#key_file = ~/.ssh/id_rsa
[octavia]
#
# From tobiko
#
# Interval to check for status changes, in seconds. (integer value)
#check_interval = 5
# Timeout, in seconds, to wait for a status change. (integer value)
#check_timeout = 360
[ping]
#
# From tobiko
#
# Number of ICMP messages to wait before ending ping command execution (integer value)
#count = 1
# Max seconds waited from ping command before self terminating himself (integer value)
#deadline = 5
# If False it will not allow ICMP messages to be delivered in smaller fragments (string
# value)
#fragmentation = <None>
# Seconds of time interval between consecutive before ICMP messages (string value)
#interval = 1
# Size in bytes of ICMP messages (including headers and payload) (integer value)
#packet_size = <None>
# Maximum time in seconds a sequence of ICMP messages is sent to a destination host
# before reporting as a failure (integer value)
#timeout = 300.0
[rhel]
#
# From tobiko
#
# Default rhel image name (string value)
#image_name = <None>
# Default rhel image URL (string value)
#image_url = <None>
# Default rhel image filename (string value)
#image_file = <None>
# Default rhel container format (string value)
#container_format = <None>
# Default rhel disk format (string value)
#disk_format = <None>
# Default rhel username (string value)
#username = <None>
# Default rhel password (string value)
#password = <None>
# Default rhel SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>
[shell]
#
# From tobiko
#
# Default shell command used for executing local commands (string value)
#command = /bin/sh -c
# Default sudo command used for executing commands as superuser or another user (string
# value)
#sudo = sudo
[ssh]
#
# From tobiko
#
# Logout debugging messages of paramiko library (boolean value)
#debug = false
# Default SSH client command (string value)
#command = /usr/bin/ssh
# Default SSH port (string value)
#port = <None>
# Default SSH username (string value)
#username = <None>
# Default user SSH configuration files (list value)
#config_files = ssh_config,.ssh/config
# Default SSH private key file(s) (list value)
#key_file = ~/.ssh/id_rsa,.ssh/id
# Set to False to disable connecting to the SSH agent (boolean value)
#allow_agent = false
# Set to True to turn on compression (boolean value)
#compress = false
# SSH connect timeout in seconds (floating point value)
#timeout = 15.0
# Maximum number of connection attempts to be tried before timeout (integer value)
#connection_attempts = 120
# Minimal seconds to wait between every failed SSH connection attempt (floating point
# value)
#connection_interval = 5.0
# Time before stopping retrying establishing an SSH connection (integer value)
#connection_timeout = 200.0
# Default SSH proxy server (string value)
#proxy_jump = <None>
# Default proxy command (string value)
#proxy_command = <None>
[testcase]
#
# From tobiko
#
# Timeout (in seconds) used for interrupting test case execution (floating point value)
#timeout = <None>
# Timeout (in seconds) used for interrupting test runner execution (floating point
# value)
#test_runner_timeout = <None>
[topology]
#
# From tobiko
#
# List of hostname nodes (list value)
#nodes = <None>
# Default SSH key to login to cloud nodes (string value)
#key_file = <None>
# Default username for SSH login (string value)
#username = <None>
# Default port for SSH login (string value)
#port = <None>
# Limit connectivity to cloud to IPv4 o IPv6 (string value)
# Possible values:
# '' - <No description provided>
# 4 - <No description provided>
# 6 - <No description provided>
#ip_version = <None>
# Regex to be used to parse date and time from the OpenStack services' log lines.
# (string value)
#log_datetime_pattern = (\d{4}-\d{2}-\d{2} [0-9:.]+) .+
[tripleo]
#
# From tobiko
#
# hostname or IP address to be used to connect to undercloud host (string value)
#undercloud_ssh_hostname = undercloud-0
# TCP port of SSH server on undercloud host (integer value)
#undercloud_ssh_port = <None>
# Username with access to stackrc and overcloudrc files (string value)
#undercloud_ssh_username = stack
# SSH key filename used to login to Undercloud node (string value)
#undercloud_ssh_key_filename = ~/.ssh/id_rsa
# Undercloud RC filename (list value)
#undercloud_rcfile = ~/stackrc
# TCP port of SSH server on overcloud hosts (integer value)
#overcloud_ssh_port = <None>
# Default username used to connect to overcloud nodes (string value)
#overcloud_ssh_username = heat-admin
# SSH key filename used to login to Overcloud nodes (string value)
#overcloud_ssh_key_filename = ~/.ssh/id_overcloud
# Overcloud RC filenames (list value)
#overcloud_rcfile = ~/overcloudrc,~/qe-Cloud-0rc
# Default IP address version to be used to connect to overcloud nodes (integer value)
#overcloud_ip_version = <None>
# Name of network used to connect to overcloud nodes (string value)
#overcloud_network_name = <None>
# path to where to export tripleo inventory file (string value)
#inventory_file = tripleo-hosts.yaml
[ubuntu]
#
# From tobiko
#
# Default ubuntu image name (string value)
#image_name = <None>
# Default ubuntu image URL (string value)
#image_url = <None>
# Default ubuntu image filename (string value)
#image_file = <None>
# Default ubuntu container format (string value)
#container_format = <None>
# Default ubuntu disk format (string value)
#disk_format = <None>
# Default ubuntu username (string value)
#username = <None>
# Default ubuntu password (string value)
#password = <None>
# Default ubuntu SSH connection timeout (seconds) (floating point value)
#connection_timeout = <None>

View File

@ -0,0 +1 @@
tobiko.conf.sample

View File

@ -27,9 +27,9 @@
import os import os
import sys import sys
BASE_DIR = os.path.dirname(os.path.abspath(__file__)) TOBIKO_DOC_DIR = os.path.dirname(os.path.realpath(__file__))
TOBIKO_DIR = os.path.abspath(os.path.join(BASE_DIR, "..", "..")) TOBIKO_SRC_DIR = os.path.realpath(f"{TOBIKO_DOC_DIR}/../..")
sys.path.insert(0, TOBIKO_DIR) sys.path.insert(0, TOBIKO_SRC_DIR)
# -- Python logging ---------------------------------------------------------- # -- Python logging ----------------------------------------------------------
@ -120,24 +120,10 @@ html_theme_options = {
# Add any paths that contain custom static files (such as style sheets) here, # Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files, # relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css". # so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static'] html_static_path = [f'{TOBIKO_DOC_DIR}/_static']
# -- Options for oslo_config.sphinxconfiggen --------------------------------- # -- Options for oslo_config.sphinxconfiggen ---------------------------------
_config_generator_config_files = [
'tobiko.conf',
]
def _get_config_generator_config_definition(conf):
config_file_path = '../../etc/oslo-config-generator/%s' % conf
# oslo_config.sphinxconfiggen appends '.conf.sample' to the filename,
# strip file extentension (.conf or .ini).
output_file_path = '_static/config-samples/%s' % conf.rsplit('.', 1)[0]
return config_file_path, output_file_path
config_generator_config_file = [ config_generator_config_file = [
_get_config_generator_config_definition(conf) (f'etc/tobiko.conf.gen', f"{TOBIKO_DOC_DIR}/_static/tobiko")
for conf in _config_generator_config_files
] ]

View File

@ -1,25 +0,0 @@
.. _configuring:
=============================
Tobiko Configuration Options
=============================
This section provides a list of all configuration options for Tobiko.
These are auto-generated from Tobiko code when this documentation is
built.
Configuration Reference
-----------------------
.. toctree::
:maxdepth: 1
tobiko.rst
Sample Configuration Files
--------------------------
.. toctree::
:maxdepth: 1
samples/tobiko.rst

View File

@ -1,8 +0,0 @@
===================
Sample tobiko.conf
===================
This sample configuration can also be viewed in `the raw format
<../../_static/config-samples/tobiko.conf.sample>`_.
.. literalinclude:: ../../_static/config-samples/tobiko.conf.sample

View File

@ -1,7 +0,0 @@
===========
tobiko.conf
===========
.. show-options::
:config-file: ../../etc/oslo-config-generator/tobiko.conf

23
doc/source/content.rst Normal file
View File

@ -0,0 +1,23 @@
=======
Content
=======
It includes the user, administrator and user guides.
It assumes that you are already familiar with other OpenStack
projects. If not, hop over to the
`OpenStack doc site <https://docs.openstack.org/>`__.
For additional documentation you can also look at
`OpenStack wiki <http://wiki.openstack.org/>`__.
Source code for this documentation page is hosted at
`source
tree <https://opendev.org/x/tobiko/src/branch/master/doc/source>`__.
.. toctree::
:maxdepth: 2
user/index
contributor/index
reference/index
etc/index

View File

@ -1,20 +0,0 @@
Tobiko Documentation Contents
-----------------------------
.. toctree::
:maxdepth: 2
user/index
contributor/index
.. toctree::
:maxdepth: 1
reference/index
Configuration Reference
-----------------------
.. toctree::
:maxdepth: 2
configuration/index

12
doc/source/etc/index.rst Normal file
View File

@ -0,0 +1,12 @@
.. _configuring:
===================
Configuration Files
===================
Tobiko accept below configuration files
.. toctree::
:maxdepth: 2
tobiko.conf

View File

@ -0,0 +1,4 @@
[DEFAULT]
namespace = tobiko
output_file = tobiko.conf.sample
wrap_width = 88

View File

@ -0,0 +1,18 @@
tobiko.conf
-----------
Tobiko will look for configuration files at below paths:
- /etc/tobiko/tobiko.conf
- ./tobiko.conf
The format of the file is the same as other `OpenStack *.conf ini files
<https://docs.openstack.org/oslo.config/latest/configuration/format.html>`_.
This section provides a list of all configuration options for
tobiko.conf file. It is being auto-generated from Tobiko code when
this documentation is being built.
It can also be viewed in `raw format <../_static/tobiko.conf.txt>`_.
.. literalinclude:: ../_static/tobiko.conf.sample

View File

@ -1,19 +1,3 @@
.. include:: ../../README.rst .. include:: ../../README.rst
Document Overview .. include:: content.rst
-----------------
This document describes the tools for final user and contributors of the
project, and assumes that you are already familiar with OpenStack from an
end-user perspective. If not, hop over to the
`OpenStack doc site <https://docs.openstack.org/>`__.
You can look for additional documentation also in the
`OpenStack wiki <http://wiki.openstack.org/>`__.
This documentation is generated by the Sphinx toolkit and lives in the `source
tree <https://opendev.org/x/tobiko/src/branch/master/doc/source>`__.
Enjoy!
.. include:: contents.rst

View File

@ -1,5 +0,0 @@
[DEFAULT]
output_file = etc/tobiko.conf.sample
wrap_width = 79
namespace = tobiko

1
etc/tobiko.conf.example Symbolic link
View File

@ -0,0 +1 @@
../doc/source/_static/tobiko.conf.sample

View File

@ -1,267 +0,0 @@
[DEFAULT]
[cirros]
#
# From tobiko
#
# Default cirros image name (string value)
#image_name = <None>
# Default cirros image URL (string value)
#image_url = <None>
# Default cirros image filename (string value)
#image_file = <None>
# Default cirros container format (string value)
#container_format = <None>
# Default cirros disk format (string value)
#disk_format = <None>
# Default cirros username (string value)
#username = <None>
# Default cirros password (string value)
#password = <None>
[glance]
#
# From tobiko
#
# Default directory where to look for image files (string value)
#image_dir = ~/.tobiko/cache/glance/images
[http]
#
# From tobiko
#
# HTTP proxy URL for Rest APIs (string value)
#http_proxy = <None>
# HTTPS proxy URL for Rest APIs (string value)
#https_proxy = <None>
# Don't use proxy server to connect to listed hosts (string value)
#no_proxy = <None>
[keystone]
#
# From tobiko
#
# Cloud name (string value)
#cloud_name = <None>
# Identity API version (integer value)
#api_version = <None>
# Identity service URL (string value)
#auth_url = <None>
# Username (string value)
#username = <None>
# Password (string value)
#password = <None>
# Project name (string value)
#project_name = <None>
# Domain name (string value)
#domain_name = <None>
# User domain name (string value)
#user_domain_name = <None>
# Project domain name (string value)
#project_domain_name = <None>
# Project domain ID (string value)
#project_domain_id = <None>
# Trust ID for trust scoping. (string value)
#trust_id = <None>
[neutron]
#
# From tobiko
#
# Network for creating floating IPs (string value)
#floating_network = <None>
# The CIDR block to allocate IPv4 subnets from (string value)
#ipv4_cidr = 10.100.0.0/16
# The mask bits for IPv4 subnets (integer value)
#ipv4_prefixlen = 24
# The CIDR block to allocate IPv6 subnets from (string value)
#ipv6_cidr = 2001:db8::/48
# The mask bits for IPv6 subnets (integer value)
#ipv6_prefixlen = 64
# Customized maximum transfer unit size
# Notes:
# - MTU values as small as 1000 has been seen breaking networking binding due
# to an unknown cause.
# - Too big MTU values (like greater than 1400) may be refused during network
# creation (integer value)
#custom_mtu_size = 1400
[nova]
#
# From tobiko
#
# Default flavor for new server instances (string value)
#flavor = <None>
# Default SSH key to login to server instances (string value)
#key_file = ~/.ssh/id_rsa
[ping]
#
# From tobiko
#
# Number of ICMP messages to wait before ending ping command execution (integer
# value)
#count = 1
# Max seconds waited from ping command before self terminating himself (integer
# value)
#deadline = 5
# If disable it will not allow ICMP messages to be delivered in smaller
# fragments (string value)
#fragmentation = True
# Seconds of time interval between consecutive before ICMP messages (string
# value)
#interval = 1
# Size in bytes of ICMP messages (including headers and payload) (integer
# value)
#packet_size = <None>
# Maximum time in seconds a sequence of ICMP messages is sent to a destination
# host before reporting as a failure (integer value)
#timeout = 90.0
[shell]
#
# From tobiko
#
# Default shell command used for executing local commands (string value)
#command = /bin/sh -c
[ssh]
#
# From tobiko
#
# Logout debugging messages of paramiko library (boolean value)
#debug = false
# Default SSH client command (string value)
#command = /usr/bin/ssh
# Default SSH port (string value)
#port = 22
# Default SSH username (string value)
#username = fressi
# Default user SSH configuration files (list value)
#config_files = /etc/ssh/ssh_config,~/.ssh/config
# Default SSH private key file (string value)
#key_file = ~/.ssh/id_rsa
# Set to False to disable connecting to the SSH agent (boolean value)
#allow_agent = false
# Set to True to turn on compression (boolean value)
#compress = false
# SSH connect timeout in seconds (floating point value)
#timeout = 5.0
# Incremental seconds to wait after every failed SSH connection attempt
# (integer value)
#connection_attempts = 60
# Minimal seconds to wait between every failed SSH connection attempt (floating
# point value)
#connection_interval = 5.0
# Default SSH proxy server (string value)
#proxy_jump = <None>
# Default proxy command (string value)
#proxy_command = <None>
[ubuntu]
#
# From tobiko
#
# Default ubuntu image name (string value)
#image_name = <None>
# Default ubuntu image URL (string value)
#image_url = <None>
# Default ubuntu image filename (string value)
#image_file = <None>
# Default ubuntu container format (string value)
#container_format = <None>
# Default ubuntu disk format (string value)
#disk_format = <None>
# Default ubuntu username (string value)
#username = <None>
# Default ubuntu password (string value)
#password = <None>
[octavia]
#
# From tobiko
#
# Interval to check for status changes, in seconds (integer value)
#check_interval = 5
# Timeout, in seconds, to wait for a status change (integer value)
#check_timeout = 360

1
tobiko.conf.example Symbolic link
View File

@ -0,0 +1 @@
doc/source/_static/tobiko.conf.sample