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
channel (though most everything can be done through `/msg chanserv` commands
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
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.
If you are curious as to who has access to a channel, you can issue this
command:
command::
/msg chanserv access #channel list
@ -347,37 +347,39 @@ channel.
Tips
----
* Collect the list of users and send a message in channel to each of them
explaining that the channel has moved.
* 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
the new channel.
* Don't leave the channel until everything is done, it's non-trivial to
rejoin because you've set up a forward!
* Collect the list of users and send a message in channel to each of them
explaining that the channel has moved.
* 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
the new channel.
* Don't leave the channel until everything is done, it's non-trivial to
rejoin because you've set up a forward!
Troubleshooting
===============
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
but not operating properly.
If the bot is stopped, start it again. Restart the bot if you see
it's running but not operating properly.
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
port, check entries on /etc/hosts for chat.freenode.net, until you find one
server that is operative. Switch the entries on /etc/hosts to choose
the right one, and restart the service with:
3. For bots on the eavesdrop server: if you don't have connection to
that port, check entries on ``/etc/hosts`` for
``chat.freenode.net``, until you find one server that is operative.
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
================================

2
doc/source/project.rst
View File

@ -61,7 +61,7 @@ And if you have any questions, please ask.
Bugs
====
The infrastructure project maintains a bug list at:
The infrastructure project maintains a bug list at::
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:
* Add a file in :cgit_file:`modules/openstack_project/manifests/` that defines a
class which specifies the configuration of the server.
* Add a file in :cgit_file:`modules/openstack_project/manifests/` that defines a
class which specifies the configuration of 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
(e.g., fooserver01.openstack.org not just fooserver.openstack.org, even
if you're replacing an existing server) and that another server with the
same does not already exist in the ansible inventory.
* 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
(e.g., fooserver01.openstack.org not just fooserver.openstack.org, even
if you're replacing an existing server) and that another server with the
same does not already exist in the ansible inventory.
* If your server needs private information such as passwords, use
hiera calls in the site manifest, and ask an infra-core team member
to manually add the private information to hiera.
* If your server needs private information such as passwords, use
hiera calls in the site manifest, and ask an infra-core team member
to manually add the private information to hiera.
* You should be able to install and configure most software only with
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
include a stanza like this in your server class::
* You should be able to install and configure most software only with
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
include a stanza like this in your server class::
extra_users:
- your_user_name
extra_users:
- your_user_name
* Add an RST file with documentation about the server in :cgit_file:`doc/source`
and add it to the index in that directory.
* Add an RST file with documentation about the server in :cgit_file:`doc/source`
and add it to the index in that directory.
SSH Access
==========
@ -147,36 +147,36 @@ SSH Access
For any of the systems managed by the OpenStack Infrastructure team, the
following practices must be observed for SSH access:
* SSH access is only permitted with SSH public/private key
authentication.
* 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
dictionary is advised, or a random string of at least 16
characters.
* To mitigate the inconvenience of using a long passphrase, users may
want to use an SSH agent so that the passphrase is only requested
once per desktop session.
* Users private keys must never be stored anywhere except their own
workstation(s). In particular, they must never be stored on any
remote server.
* 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 (see above). Instead SSH agent forwarding may be used.
However due to the potential for a compromised intermediate machine
to ask the agent to sign requests without the users knowledge, in
this case only an SSH agent that interactively prompts the user
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
the confirmation constraint ('ssh-add -c').
* The number of SSH keys that are configured to permit access to
OpenStack machines should be kept to a minimum.
* OpenStack Infrastructure machines must use puppet to centrally manage and
configure user accounts, and the SSH authorized_keys files from the
openstack-infra/system-config repository.
* 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
then the old one removed. Be sure to run puppet on the backup
servers to make sure they are updated.
* SSH access is only permitted with SSH public/private key
authentication.
* 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
dictionary is advised, or a random string of at least 16
characters.
* To mitigate the inconvenience of using a long passphrase, users may
want to use an SSH agent so that the passphrase is only requested
once per desktop session.
* Users private keys must never be stored anywhere except their own
workstation(s). In particular, they must never be stored on any
remote server.
* 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 (see above). Instead SSH agent forwarding may be used.
However due to the potential for a compromised intermediate machine
to ask the agent to sign requests without the users knowledge, in
this case only an SSH agent that interactively prompts the user
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
the confirmation constraint ('ssh-add -c').
* The number of SSH keys that are configured to permit access to
OpenStack machines should be kept to a minimum.
* OpenStack Infrastructure machines must use puppet to centrally manage and
configure user accounts, and the SSH authorized_keys files from the
openstack-infra/system-config repository.
* 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
then the old one removed. Be sure to run puppet on the backup
servers to make sure they are updated.
GitHub Access
@ -204,8 +204,8 @@ Backups
Off-site backups are made to two servers:
* backup01.ord.rax.ci.openstack.org
* TBD
* backup01.ord.rax.ci.openstack.org
* TBD
Puppet is used to perform the initial configuration of those machines,
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
account. Once logged in you will need to do several things:
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
SSH to Gerrit in order to read the event stream.
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
SSH to Gerrit in order to read the event stream.
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
comments what this CI system exists to test. The name should have three
pieces ``Organization`` ``Product/technology`` ``CI designator``. The
organization value should be your company name or other organization
affiliation. Product/technology should describe the product or technology
you are testing in conjunction with OpenStack. This should be the name of
a component which cannot be tested in the official OpenStack
infrastructure (requires particular physical hardware, proprietary
software, some hypervisor feature not available in public clouds,
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
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
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
something like ``IBM DB2 CI``.
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
comments what this CI system exists to test. The name should have three
pieces ``Organization`` ``Product/technology`` ``CI designator``. The
organization value should be your company name or other organization
affiliation. Product/technology should describe the product or technology
you are testing in conjunction with OpenStack. This should be the name of
a component which cannot be tested in the official OpenStack
infrastructure (requires particular physical hardware, proprietary
software, some hypervisor feature not available in public clouds,
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
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
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
something like ``IBM DB2 CI``.
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
ssh key using ``ssh-keygen``. You want to give Gerrit the contents of
the generated id_rsa.pub file.
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
ssh key using ``ssh-keygen``. You want to give Gerrit the contents of
the generated id_rsa.pub file.
Note you should also subscribe to the `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
Gerrit GUI parser, configure the ``URL to post`` parameter (under the
``Gerrit Reporting Values`` section) for each job. The correct value for this
paramater is:
parameter is::
\* $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
system for voting permissions
* openstack-dev@lists.openstack.org
* use tags [Infra][Nova] for the Nova program, please replace
[Nova] with [Program], where [Program] is the name of the
program your CI account will test
* openstack-dev@lists.openstack.org
* use tags [Infra][Nova] for the Nova program, please replace
[Nova] with [Program], where [Program] is the name of the
program your CI account will test
* present your account history
* address any questions and concerns with your system