diff --git a/doc/source/irc.rst b/doc/source/irc.rst index 223f5380ad..d77598e7d7 100644 --- a/doc/source/irc.rst +++ b/doc/source/irc.rst @@ -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 ================================ diff --git a/doc/source/project.rst b/doc/source/project.rst index 81ec41328a..513fa52202 100644 --- a/doc/source/project.rst +++ b/doc/source/project.rst @@ -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 diff --git a/doc/source/sysadmin.rst b/doc/source/sysadmin.rst index 34bb521c19..c9f9b12b71 100644 --- a/doc/source/sysadmin.rst +++ b/doc/source/sysadmin.rst @@ -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 diff --git a/doc/source/third_party.rst b/doc/source/third_party.rst index 22d995ef59..10242da283 100644 --- a/doc/source/third_party.rst +++ b/doc/source/third_party.rst @@ -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 `_ @@ -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