static-component.md

title: Managing static site components

This documentation is about administrating the static site components, from a sysadmin perspective. User documentation lives in doc/static-sites.

Adding a new component

1. add the component to Puppet, in modules/roles/misc/static-components.yaml:

   onionperf.torproject.org:
     master: staticiforme.torproject.org
     source: staticiforme.torproject.org:/srv/onionperf.torproject.org/htdocs/

2. create the directory on staticiforme:

   ssh staticiforme "mkdir -p /srv/onionperf.torproject.org/htdocs/ \
       && chown torwww:torwww /srv/onionperf.torproject.org/{,htdocs}"

3. add the host to DNS, if not already present, see howto/dns, for example add this line in dns/domains/torproject.org:

   onionperf	IN	CNAME	static

4. add an Apache virtual host, by adding a line like this in howto/puppet to modules/roles/templates/static-mirroring/vhost/static-vhosts.erb:

   vhost(lines, 'onionperf.torproject.org')

5. add an SSL service, by adding a line in howto/puppet to modules/roles/manifests/static_mirror_web.pp:

   ssl::service { onionperf.torproject.org': ensure => 'ifstatic', notify  => Exec['service apache2 reload'], key => true, }

   This also requires generating an X509 certificate, for which we use Let's encrypt. See howto/letsencrypt for details.

6. add an onion service, by adding another onion::service line in howto/puppet to modules/roles/manifests/static_mirror_onion.pp:

   onion::service {
       [...]
       'onionperf.torproject.org',
       [...]
   }

7. run Puppet on the master and mirrors:

   ssh staticiforme puppet agent -t
   cumin 'C:roles::static_mirror_web' 'puppet agent -t'

   The latter is done with howto/cumin, see also howto/puppet for a way to do jobs on all hosts.

8. consider creating a new role and group for the component if none match its purpose, see howto/create-a-new-user for details:

   ssh alberti.torproject.org ldapvi -ZZ --encoding=ASCII --ldap-conf -h db.torproject.org -D "uid=$USER,ou=users,dc=torproject,dc=org"

9. if you created a new group, you will probably need to modify the sudoers file to grant a user access to the role/group, see modules/sudo/files/sudoers in the tor-puppet repository (and howto/puppet to learn about how to make changes to Puppet). onionperf is a good example of how to create a sudoers file. edit the file with visudo so it checks the syntax:

   visudo -f modules/sudo/files/sudoers

   This, for example, is the line that was added for onionperf:

   %torwww,%metrics		STATICMASTER=(mirroradm)	NOPASSWD: /usr/local/bin/static-master-update-component onionperf.torproject.org, /usr/local/bin/static-update-component onionperf.torproject.org

10. add to nagios monitoring, in tor-nagios/config/nagios-master.cfg:

    -
        name: mirror static sync - atlas
        check: "dsa_check_staticsync!atlas.torproject.org"
        hosts: global
        servicegroups: mirror

Removing a component

1. remove the component to Puppet, in modules/roles/misc/static-components.yaml

2. remove the host to DNS, if not already present, see howto/dns. this can be either in dns/domains.git or dns/auto-dns.git

3. remove the Apache virtual host, by removing a line like this in howto/puppet to modules/roles/templates/static-mirroring/vhost/static-vhosts.erb:

   vhost(lines, 'onionperf.torproject.org')

4. remove an SSL service, by removing a line in howto/puppet to modules/roles/manifests/static_mirror_web.pp:

   ssl::service { onionperf.torproject.org': ensure => 'ifstatic', notify  => Exec['service apache2 reload'], key => true, }

5. remove the Let's encrypt certificate, see howto/letsencrypt for details

6. remove onion service, by removing another onion::service line in howto/puppet to modules/roles/manifests/static_mirror_onion.pp:

   onion::service {
       [...]
       'onionperf.torproject.org',
       [...]
   }

7. remove the sudo rules for the role user

8. remove the home directory specified on the server (often staticiforme, but can be elsewhere) and mirrors, for example:

   ssh staticiforme "mv /home/ooni /home/ooni-OLD ; echo rm -rf /home/ooni-OLD | at now + 7 days"
   cumin -o txt 'C:roles::static_mirror_web' 'mv /srv/static.torproject.org/mirrors/ooni.torproject.org /srv/static.torproject.org/mirrors/ooni.torproject.org-OLD'
   cumin -o txt 'C:roles::static_mirror_web' 'echo rm -rf /srv/static.torproject.org/mirrors/ooni.torproject.org-OLD | at now + 7 days'

9. consider removing the role user and group in LDAP, if there are no files left owned by that user

10. remove from nagios, e.g.:

    name: mirror static sync - atlas
    check: "dsa_check_staticsync!atlas.torproject.org"
    hosts: global
    servicegroups: mirror