opendev/system-config
Code Issues Proposed changes

Cleanup docs formatting

Browse Source 
Fix indents of some pages, the wrong indent let to gray bars besides
them.

Also, fix a typo and add some markup.

Change-Id: I6e7126ef7b782b376efcc7c6d69c6de9a504ddb5
This commit is contained in:
Andreas Jaeger 2018-08-24 22:08:36 +02:00
parent dde24421d0
commit 1c6b4876eb
4 changed files with 103 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
doc/source/irc.rst
View File

@ -278,17 +278,17 @@ commands which may be required for channel operators.
Operator status is sometimes required to perform certain commands in your Operator status is sometimes required to perform certain commands in your
channel (though most everything can be done through `/msg chanserv` commands channel (though most everything can be done through `/msg chanserv` commands
instead if permission flags are set correctly). To give yourself operator instead if permission flags are set correctly). To give yourself operator
status in a channel, use the following command: status in a channel, use the following command::
/msg chanserv op #channel /msg chanserv op #channel
You don't need to become an operator to change the topic, this can be done You don't need to become an operator to change the topic, this can be done
via Chanserv: via Chanserv::
/msg chanserv topic #channel New topic goes here. /msg chanserv topic #channel New topic goes here.
If you are curious as to who has access to a channel, you can issue this If you are curious as to who has access to a channel, you can issue this
command: command::
/msg chanserv access #channel list /msg chanserv access #channel list
@ -347,37 +347,39 @@ channel.
Tips Tips
---- ----
* Collect the list of users and send a message in channel to each of them * Collect the list of users and send a message in channel to each of them
explaining that the channel has moved. explaining that the channel has moved.
* Some folks simply won't leave and join the new channel, you can /kick * Some folks simply won't leave and join the new channel, you can /kick
them after a bit of time (a day? a week?) to get their client to join them after a bit of time (a day? a week?) to get their client to join
the new channel. the new channel.
* Don't leave the channel until everything is done, it's non-trivial to * Don't leave the channel until everything is done, it's non-trivial to
rejoin because you've set up a forward! rejoin because you've set up a forward!
Troubleshooting Troubleshooting
=============== ===============
Bots may stop responding, common steps to troubleshoot the problem are: Bots may stop responding, common steps to troubleshoot the problem are:
1. Check status of the bot, with: 1. Check status of the bot, with::
service xxxbot status service xxxbot status
If bot is stopped, start it again. Restart the bot if you see it's running If the bot is stopped, start it again. Restart the bot if you see
but not operating properly. it's running but not operating properly.
2. On bot restart, it may show problems connecting to chat.freenode.net. 2. On bot restart, it may show problems connecting to chat.freenode.net.
If bot logs show it's stopped on connection, you can manually try with: If bot logs show it's stopped on connection, you can manually try
with::
telnet chat.freenode.net 6667 telnet chat.freenode.net 6667
3. For bots on the eavesdrop server: if you don't have connection to that 3. For bots on the eavesdrop server: if you don't have connection to
port, check entries on /etc/hosts for chat.freenode.net, until you find one that port, check entries on ``/etc/hosts`` for
server that is operative. Switch the entries on /etc/hosts to choose ``chat.freenode.net``, until you find one server that is operative.
the right one, and restart the service with: Switch the entries on ``/etc/hosts`` to choose the right one, and
restart the service with::
sudo service xxxbot restart sudo service xxxbot restart
Registering a Nick for a New Bot Registering a Nick for a New Bot
================================ ================================

2
doc/source/project.rst
View File

@ -61,7 +61,7 @@ And if you have any questions, please ask.
Bugs Bugs
==== ====
The infrastructure project maintains a bug list at: The infrastructure project maintains a bug list at::
https://storyboard.openstack.org/#!/project_group/55 https://storyboard.openstack.org/#!/project_group/55

100
doc/source/sysadmin.rst
View File

@ -117,29 +117,29 @@ Adding a New Server
To create a new server, do the following: To create a new server, do the following:
* Add a file in :cgit_file:`modules/openstack_project/manifests/` that defines a * Add a file in :cgit_file:`modules/openstack_project/manifests/` that defines a
class which specifies the configuration of the server. class which specifies the configuration of the server.
* Add a node pattern entry in :cgit_file:`manifests/site.pp` for the server * Add a node pattern entry in :cgit_file:`manifests/site.pp` for the server
that uses that class. Make sure it supports an ordinal naming pattern that uses that class. Make sure it supports an ordinal naming pattern
(e.g., fooserver01.openstack.org not just fooserver.openstack.org, even (e.g., fooserver01.openstack.org not just fooserver.openstack.org, even
if you're replacing an existing server) and that another server with the if you're replacing an existing server) and that another server with the
same does not already exist in the ansible inventory. same does not already exist in the ansible inventory.
* If your server needs private information such as passwords, use * If your server needs private information such as passwords, use
hiera calls in the site manifest, and ask an infra-core team member hiera calls in the site manifest, and ask an infra-core team member
to manually add the private information to hiera. to manually add the private information to hiera.
* You should be able to install and configure most software only with * You should be able to install and configure most software only with
ansible or puppet. Nonetheless, if you need SSH access to the host, ansible or puppet. Nonetheless, if you need SSH access to the host,
add your public key to :cgit_file:`playbooks/group_vars/all.yaml` and add your public key to :cgit_file:`playbooks/group_vars/all.yaml` and
include a stanza like this in your server class:: include a stanza like this in your server class::
extra_users: extra_users:
- your_user_name - your_user_name
* Add an RST file with documentation about the server in :cgit_file:`doc/source` * Add an RST file with documentation about the server in :cgit_file:`doc/source`
and add it to the index in that directory. and add it to the index in that directory.
SSH Access SSH Access
========== ==========
@ -147,36 +147,36 @@ SSH Access
For any of the systems managed by the OpenStack Infrastructure team, the For any of the systems managed by the OpenStack Infrastructure team, the
following practices must be observed for SSH access: following practices must be observed for SSH access:
* SSH access is only permitted with SSH public/private key * SSH access is only permitted with SSH public/private key
authentication. authentication.
* Users must use a strong passphrase to protect their private key. A * Users must use a strong passphrase to protect their private key. A
passphrase of several words, at least one of which is not in a passphrase of several words, at least one of which is not in a
dictionary is advised, or a random string of at least 16 dictionary is advised, or a random string of at least 16
characters. characters.
* To mitigate the inconvenience of using a long passphrase, users may * To mitigate the inconvenience of using a long passphrase, users may
want to use an SSH agent so that the passphrase is only requested want to use an SSH agent so that the passphrase is only requested
once per desktop session. once per desktop session.
* Users private keys must never be stored anywhere except their own * Users private keys must never be stored anywhere except their own
workstation(s). In particular, they must never be stored on any workstation(s). In particular, they must never be stored on any
remote server. remote server.
* If users need to 'hop' from a server or bastion host to another * If users need to 'hop' from a server or bastion host to another
machine, they must not copy a private key to the intermediate machine, they must not copy a private key to the intermediate
machine (see above). Instead SSH agent forwarding may be used. machine (see above). Instead SSH agent forwarding may be used.
However due to the potential for a compromised intermediate machine However due to the potential for a compromised intermediate machine
to ask the agent to sign requests without the users knowledge, in to ask the agent to sign requests without the users knowledge, in
this case only an SSH agent that interactively prompts the user this case only an SSH agent that interactively prompts the user
each time a signing request (ie, ssh-agent, but not gnome-keyring) each time a signing request (ie, ssh-agent, but not gnome-keyring)
is received should be used, and the SSH keys should be added with is received should be used, and the SSH keys should be added with
the confirmation constraint ('ssh-add -c'). the confirmation constraint ('ssh-add -c').
* The number of SSH keys that are configured to permit access to * The number of SSH keys that are configured to permit access to
OpenStack machines should be kept to a minimum. OpenStack machines should be kept to a minimum.
* OpenStack Infrastructure machines must use puppet to centrally manage and * OpenStack Infrastructure machines must use puppet to centrally manage and
configure user accounts, and the SSH authorized_keys files from the configure user accounts, and the SSH authorized_keys files from the
openstack-infra/system-config repository. openstack-infra/system-config repository.
* SSH keys should be periodically rotated (at least once per year). * SSH keys should be periodically rotated (at least once per year).
During rotation, a new key can be added to puppet for a time, and During rotation, a new key can be added to puppet for a time, and
then the old one removed. Be sure to run puppet on the backup then the old one removed. Be sure to run puppet on the backup
servers to make sure they are updated. servers to make sure they are updated.
GitHub Access GitHub Access
@ -204,8 +204,8 @@ Backups
Off-site backups are made to two servers: Off-site backups are made to two servers:
* backup01.ord.rax.ci.openstack.org * backup01.ord.rax.ci.openstack.org
* TBD * TBD
Puppet is used to perform the initial configuration of those machines, Puppet is used to perform the initial configuration of those machines,
but to protect them from unauthorized access in case access to the but to protect them from unauthorized access in case access to the

58
doc/source/third_party.rst
View File

@ -166,32 +166,32 @@ Once you have created this account with the OpenID provider you can log
into Gerrit with that new account as you would with your normal user into Gerrit with that new account as you would with your normal user
account. Once logged in you will need to do several things: account. Once logged in you will need to do several things:
1. Set an SSH username at https://review.openstack.org/#/settings/ if 1. Set an SSH username at https://review.openstack.org/#/settings/ if
it isn't already set. This is the username your CI system will use to it isn't already set. This is the username your CI system will use to
SSH to Gerrit in order to read the event stream. SSH to Gerrit in order to read the event stream.
2. Set the account's fullname at https://review.openstack.org/#/settings/contact 2. Set the account's fullname at https://review.openstack.org/#/settings/contact
This name should follow a few rules in order to make it clear in Gerrit This name should follow a few rules in order to make it clear in Gerrit
comments what this CI system exists to test. The name should have three comments what this CI system exists to test. The name should have three
pieces ``Organization`` ``Product/technology`` ``CI designator``. The pieces ``Organization`` ``Product/technology`` ``CI designator``. The
organization value should be your company name or other organization organization value should be your company name or other organization
affiliation. Product/technology should describe the product or technology affiliation. Product/technology should describe the product or technology
you are testing in conjunction with OpenStack. This should be the name of you are testing in conjunction with OpenStack. This should be the name of
a component which cannot be tested in the official OpenStack a component which cannot be tested in the official OpenStack
infrastructure (requires particular physical hardware, proprietary infrastructure (requires particular physical hardware, proprietary
software, some hypervisor feature not available in public clouds, software, some hypervisor feature not available in public clouds,
et cetera). Note this should not be the name of an OpenStack project but et cetera). Note this should not be the name of an OpenStack project but
rather the thing you are testing with OpenStack projects. And finally rather the thing you are testing with OpenStack projects. And finally
the CI designator is used to denote this is a CI system so that automatic the CI designator is used to denote this is a CI system so that automatic
Gerrit comment parsers can filter these comments out. This value should Gerrit comment parsers can filter these comments out. This value should
be ``CI`` for most CI systems but can be ``Bot`` if you are not be ``CI`` for most CI systems but can be ``Bot`` if you are not
performing continuous integration. An example of a proper name would be performing continuous integration. An example of a proper name would be
something like ``IBM DB2 CI``. something like ``IBM DB2 CI``.
3. Add the SSH public key you will be using to the Gerrit account at 3. Add the SSH public key you will be using to the Gerrit account at
https://review.openstack.org/#/settings/ssh-keys You can generate an https://review.openstack.org/#/settings/ssh-keys You can generate an
ssh key using ``ssh-keygen``. You want to give Gerrit the contents of ssh key using ``ssh-keygen``. You want to give Gerrit the contents of
the generated id_rsa.pub file. the generated id_rsa.pub file.
Note you should also subscribe to the `third-party-announce Note you should also subscribe to the `third-party-announce
<http://lists.openstack.org/cgi-bin/mailman/listinfo/third-party-announce>`_ <http://lists.openstack.org/cgi-bin/mailman/listinfo/third-party-announce>`_
@ -278,7 +278,7 @@ should configure as follows::
To format the result's message in a way that works with the current OpenStack To format the result's message in a way that works with the current OpenStack
Gerrit GUI parser, configure the ``URL to post`` parameter (under the Gerrit GUI parser, configure the ``URL to post`` parameter (under the
``Gerrit Reporting Values`` section) for each job. The correct value for this ``Gerrit Reporting Values`` section) for each job. The correct value for this
paramater is: parameter is::
\* $JOB_NAME $BUILD_URL \* $JOB_NAME $BUILD_URL
@ -441,10 +441,10 @@ chance of success if you follow these steps:
* send an email to the openstack-dev mailing list nominating your * send an email to the openstack-dev mailing list nominating your
system for voting permissions system for voting permissions
* openstack-dev@lists.openstack.org * openstack-dev@lists.openstack.org
* use tags [Infra][Nova] for the Nova program, please replace * use tags [Infra][Nova] for the Nova program, please replace
[Nova] with [Program], where [Program] is the name of the [Nova] with [Program], where [Program] is the name of the
program your CI account will test program your CI account will test
* present your account history * present your account history
* address any questions and concerns with your system * address any questions and concerns with your system