Merge pull request #767 from pmcmaw/readme_update

[puppet-modules/puppetlabs-apt.git] / README.md

diff --git a/README.md b/README.md
index 56687f2e448686ea04569219446b1c53fb4ede97..7fafd799e40082654acc58b8d5cf840d56affb8c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -226,6 +226,38 @@ apt::source { "archive.ubuntu.com-${lsbdistcodename}-backports":
 }
 ```
 
+### Manage login configuration settings for an APT source or proxy in `/etc/apt/auth.conf`
+
+Starting with APT version 1.5 you can define login configuration settings (like
+username and password) for APT sources or proxies that require authentication
+in the file `/etc/apt/auth.conf`. This is preferable to embedding login
+information directly in `source.list` entries which are usually world-readable.
+
+The file `/etc/apt/auth.conf` follows the format of netrc (as used by ftp or
+curl) and has restrictive file permissions. See
+https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for details.
+
+Use the optional `apt::auth_conf_entries` parameter to specify an array of
+hashes containing login configuration settings. These hashes may only contain
+the keys `machine`, `login` and `password`.
+
+```puppet
+class { 'apt':
+  auth_conf_entries => [
+    {
+      'machine'  => 'apt-proxy.example.net',
+      'login'    => 'proxylogin',
+      'password' => 'proxypassword',
+    },
+    {
+      'machine'  => 'apt.example.com/ubuntu',
+      'login'    => 'reader',
+      'password' => 'supersecret',
+    },
+  ],
+}
+```
+
 ## Reference
 
 ### Classes
@@ -313,6 +345,8 @@ All parameters are optional unless specified.
 
 * `settings`: Creates new `apt::setting` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}.
 
+* `auth_conf_entries`: An optional array of login configuration settings (hashes) that will be recorded in the file `/etc/apt/auth.conf`. This file has a netrc-like format (similar to what curl uses) and contains the login configuration for APT sources and proxies that require authentication. See https://manpages.debian.org/testing/apt/apt_auth.conf.5.en.html for details. If specified each hash must contain the keys `machine`, `login` and `password` and no others. Default: [].
+
 * `sources`: Creates new `apt::source` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}.
 
 * `pins`: Creates new `apt::pin` resources. Valid options: a hash to be passed to the [`create_resources` function](https://docs.puppetlabs.com/references/latest/function.html#createresources). Default: {}.