document the files i know come from outside puppet

system. See also the [LDAP design document](ldap#Design) for more information

about how LDAP works.

### External data sources

### Nagios integration

TODO: document which parts of Puppet come from external entities. I

know of at least NRPE and Let's encrypt, but there could be others?

Nagios (which is really Icinga, but let's call it Nagios because

that's how it's called everywhere in the source) is hooked into Puppet

through an external sync system. Our [Nagios deployment](nagios) operates

through Git hooks which run a special `Makefile` that compiles and

deploys the Icinga configuration, but also compiles the client-side

NRPE configuration.

The NRPE configuration is generated on the Nagios server and then

pushed to the Puppet server with `rsync` over SSH, using a public key

distributed by Puppet from the `roles::puppetmaster` class. That key

has a restricted `command` field which limits access to the Puppet

manifest, in this single file:

    /etc/puppet/modules/nagios/files/tor-nagios/generated/nrpe_tor.cfg

This file then gets distributed to all nodes through the

`nagios::client` class using a simple `File` resource.

So when a Nagios check is added or changed, Puppet needs to run on all

the affected host for the check to take affect, on top of, of course,

adding the check into the Nagios git repository.

### Let's Encrypt TLS certificates

Public TLS certificates, as issued by Let's Encrypted, are distributed

by Puppet. Those certificates are generated by the "letsencrypt" Git

repository (see the [TLS documentation](tls) for details on that

workflow). The relevant part, as far as Puppet is concerned, is that

certificates magically end up in the following directory when a

certificate is issued or (automatically) renewed:

    /srv/puppet.torproject.org/from-letsencrypt

See also the [TLS deployment docs](tls#lets-encrypt-workflow) for how that directory gets

populated.

Normally, those files would not be available from the Puppet

manifests, but the `ssl` Puppet module uses a special trick whereby

those files are read by Puppet `.erb` templates. For example, this is

how `.crt` files get generated on the Puppet master, in

`modules/ssl/templates/crt.erb`:

    <%=

      fn = "/srv/puppet.torproject.org/from-letsencrypt/#{@name}.crt"

      out = File.read(fn)

      out

    %>

Similar templates exist for the other files.

Those certificates should not be confused with the "auto-ca" TLS

certificates in use internally and which are deployed directly in

`/etc/puppet/modules/ssl/files/`, see below.

### Internal auto-ca TLS certificates

The Puppet server also manages an internal CA which we informally call

"auto-ca". Those certificates are internal in that they are used to

authentify nodes to each other, not to the public. They are used, for

example, to encrypt connexions between mail servers (in Postfix) and

[backup servers](backup) (in Bacula).

The auto-ca deploys those certificates directly inside the Puppet

server checkout, in `/etc/puppet/modules/ssl/files/certs/` and

`.../clientcerts/`. Details of that system are available in the [TLS documentation](tls#internal-auto-ca).

## Issues