This documentation is about administrating the static site components, from a sysadmin perspective. User documentation lives in 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 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 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 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 letsencrypt for details.

  6. add an onion service, by adding another onion::service line in 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 cumin, see also 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 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 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
    

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 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 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 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 letsencrypt for details

  6. remove onion service, by removing another onion::service line in 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