You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
9.[Transfer Notice - Notice of authorship change](#transfer-notice)
14
+
10.[Contributors - List of module contributors](#contributors)
15
+
8.[Release Notes - Notes on the most recent updates to the module](#release-notes)
9
16
10
-
Puppet module for PostgreSQL resources
11
-
======================================
12
17
13
-
This module provides the following classes and types for managing postgres:
18
+
Overview
19
+
--------
14
20
15
-
*`postgresql::server`
16
-
*`postgresql::client`
17
-
*`postgresql::db`
18
-
*`postgresql::database`
19
-
*`postgresql::role`
20
-
*`postgresql::database_user` (just for clarity; users are roles in postgres)
21
-
*`postgresql::database_grant`
22
-
*`postgresql::initdb`
21
+
The PostgreSQL module allows you to easily manage postgres databases with Puppet.
23
22
24
-
And the fallback, analogous to exec resources, only for SQL statements:
23
+
Module Description
24
+
-------------------
25
25
26
-
*`postgresql_psql`
26
+
PostgreSQL is a high-performance, free, open-source relational database server. The postgresql module allows you to manage PostgreSQL packages and services on several operating systems, while also supporting basic management of PostgreSQL databases and users. The module offers support for managing firewall for postgres ports on RedHat-based distros, as well as support for basic management of common security settings.
27
27
28
-
Basic usage
29
-
-----------
28
+
Setup
29
+
-----
30
+
31
+
**What puppetlabs-PostgreSQL affects:**
32
+
33
+
* package/service/configuration files for PostgreSQL
34
+
* listened-to ports
35
+
* system firewall (optional)
36
+
* IP and mask (optional)
37
+
38
+
**Introductory Questions**
39
+
40
+
The postgresql module offers many security configuration settings. Before getting started, you will want to consider:
30
41
31
-
Manage a PostgreSQL server with sane defaults (login via `sudo -u postgres psql`):
42
+
* Do you want/need to allow remote connections?
43
+
* If yes, what about TCP connections?
44
+
* Would you prefer to work around your current firewall settings or overwrite some of them?
45
+
* How restrictive do you want the database superuser's permissions to be?
32
46
33
-
```Puppet
34
-
include postgresql::server
35
-
```
47
+
Your answers to these questions will determine which of the module's parameters you'll want to specify values for.
36
48
37
-
...or a custom configuration:
49
+
###Configuring the server
38
50
39
-
```Puppet
40
-
class { 'postgresql::server':
41
-
config_hash => {
51
+
The main configuration you’ll need to do will be around the `postgresql::server` class. The default parameters are reasonable, but fairly restrictive regarding permissions for who can connect and from where. To manage a PostgreSQL server with sane defaults:
52
+
53
+
include postgresql::server
54
+
55
+
For a more customized, less restrictive configuration:
56
+
57
+
class { 'postgresql::server':
58
+
config_hash => {
42
59
'ip_mask_deny_postgres_user' => '0.0.0.0/32',
43
60
'ip_mask_allow_all_users' => '0.0.0.0/0',
44
61
'listen_addresses' => '*',
45
62
'ipv4acls' => ['hostssl all johndoe 192.168.0.0/24 cert'],
46
63
'manage_redhat_firewall' => true,
47
64
'postgres_password' => 'TPSrep0rt!',
48
-
},
49
-
}
50
-
```
65
+
},
66
+
}
67
+
68
+
Once you've completed your configuration of `postgresql::server`, you can test out your settings from the command line:
69
+
70
+
$ psql -h localhost -U postgres
71
+
$ psql -h my.postgres.server -U
72
+
73
+
If you get an error message from these commands, it means that your permissions are set in a way that restricts access from where you’re trying to connect. That might be a good thing or a bad thing, depending on your goals.
74
+
75
+
###Configuring the database
76
+
77
+
There are many ways to set up a postgres database using the `postgresql::db` class. For instance, to set up a database for PuppetDB (this assumes you’ve already got the `postgresql::server` set up to your liking in your manifest, as discussed above):
78
+
79
+
postgresl::db { 'mydatabasename':
80
+
user => 'mydatabaseuser',
81
+
password => 'mypassword'
82
+
}
83
+
84
+
To manage users, roles and permissions:
85
+
86
+
postgresql::database_user{'marmot':
87
+
password => 'foo',
88
+
}
89
+
90
+
postgresql::database_grant{'test1':
91
+
privilege => 'ALL',
92
+
db => 'test1',
93
+
role => 'dan',
94
+
}
95
+
96
+
In this example, you would grant ALL privileges on the test1 database to the user or group specified by dan.
97
+
98
+
At this point, you would just need to plunk these database name/username/password values into your PuppetDB config files, and you are good to go.
99
+
100
+
Usage
101
+
------
102
+
103
+
The postgresql module comes with many options for configuring the server. While you are unlikely to use all of the below settings, they allow you a decent amount of control over your security settings.
104
+
105
+
###postgresql::server
106
+
Here are the options that you can set in the `config_hash` parameter of `postgresql::server`:
107
+
108
+
####`postgres_password`
109
+
This value defaults to 'undef', meaning the “super user” account in the postgres
110
+
database is a user called ‘postgres’ and this account does not have a password. If you provide this setting, the module will set the password for the ‘postgres’ user to your specified value.
51
111
52
-
Simple management of a database and user:
112
+
####`listen_addresses`
113
+
This value defaults to 'localhost', meaning the postgres server will only accept
114
+
connections from localhost. If you’d like to be able to connect to postgres from remote machines, you can override this setting. A value of ‘*’ will tell postgres to accept connections from any remote machine. Alternately, you can specify a comma-separated list of hostnames or IP addresses. (For more info, have a look at the `postgresql.conf` file from your system’s postgres package).
53
115
54
-
```Puppet
55
-
postgresl::db { 'mydatabasename':
56
-
user => 'mydatabaseuser',
57
-
password => 'mypassword'
58
-
}
59
-
```
116
+
####`manage_redhat_firewall`
117
+
This value defaults to 'false'. Many RedHat-based distros ship with a fairly restrictive firewall configuration which will block the port that postgres tries to listen on. If you’d like for the puppet module to open this port for you (using the [puppetlabs-firewall](http://forge.puppetlabs.com/puppetlabs/firewall)
118
+
module), change this value to true. *[This parameter is likely to change in future versions. Possible changes include support for non-RedHat systems and finer-grained control over the firewall rule (currently, it simply opens up the postgres port to all TCP connections).]*
60
119
61
-
Manage users / roles and permissions:
120
+
####`ip_mask_allow_all_users`
121
+
This value defaults to '127.0.0.1/32'. By default, Postgres does not allow any database user accounts to connect via TCP from remote machines. If you’d like to allow them to, you can override this setting. You might set it to “0.0.0.0/0” to allow database users to connect from any remote machine, or “192.168.0.0/16” to allow connections from any machine on your local 192.168 subnet.
62
122
63
-
```Puppet
64
-
postgresql::database_user{'marmot':
65
-
password => 'foo',
66
-
}
123
+
####`ip_mask_deny_postgres_user`
124
+
This value defaults to '0.0.0.0/0'. Sometimes it can be useful to block the superuser account from remote connections if you are allowing other database users to connect remotely. Set this to an IP and mask for which you want to deny connections by the postgres superuser account. So, e.g., the default value of “0.0.0.0/0” will match any remote IP and deny access, so the postgres user won’t be able to connect remotely at all. Conversely, a value of “0.0.0.0/32” would not match any remote IP, and thus the deny rule will not be applied and the postgres user will be allowed to connect.
67
125
68
-
postgresql::database_grant{'grant select to marmot':
69
-
grantee => 'marmot',
70
-
on_object => 'my_table',
71
-
perm => 'select',
72
-
require => Postgresql::User['marmot'],
73
-
}
74
-
```
126
+
####`pg_hba_conf_path`
127
+
If, for some reason, your system stores the postgres pg_hba.conf file in a non-standard location, you can override the path here.
75
128
76
-
etc, etc.
129
+
####`postgresql_conf_path`
130
+
If, for some reason, your system stores the postgres postgresql.conf file in a
131
+
non-standard location, you can override the path here.
77
132
133
+
####`ipv4acls`
134
+
List of strings for access control for connection method, users, databases, IPv4 addresses; see [postgresql documentation](http://www.postgresql.org/docs/9.2/static/auth-pg-hba-conf.html) about pg_hba.conf for information (please note that the link will take you to documentation for the most recent version of Postgres, however links for earlier versions can be found on that page).
135
+
136
+
####`ipv6acls`
137
+
List of strings for access control for connection method, users, databases, IPv6
138
+
addresses; see [postgresql documentation](http://www.postgresql.org/docs/9.2/static/auth-pg-hba-conf.html) about pg_hba.conf for information (please note that the link will take you to documentation for the most recent version of Postgres, however links for earlier versions can be found on that page).
78
139
79
-
Automated testing
80
-
-----------------
140
+
###postgresql::client
81
141
82
-
Install and setup an [RVM](http://beginrescueend.com/) with
83
-
[vagrant](http://vagrantup.com/),
84
-
[sahara](https://github.com/jedi4ever/sahara), and
85
-
[rspec](http://rspec.info/)
142
+
This class installs postgresql client software. Alter the following parameters if you have a custom version you would like to install (Note: don't forget to make sure to add any necessary yum or apt repositories if specifying a custom version):
143
+
144
+
####`package_name`
145
+
The name of the postgresql client package.
146
+
147
+
####`package_ensure`
148
+
The ensure parameter passed on to postgresql client package resource.
149
+
150
+
### Custom Functions
151
+
152
+
If you need to generate a postgres encrypted password, use `postgresql_password`. You can call it from your production manifests if you don’t mind them containing the clear text versions of your passwords, or you can call it from the command line and then copy and paste the encrypted password into your manifest:
There are two types of tests distributed with the module. The first set is the
159
+
“traditional” Puppet manifest-style smoke tests. You can use these to experiment with the module on a virtual machine or other test environment, via `puppet apply`. You should see the following files in the tests directory:
160
+
161
+
* init.pp: just installs the postgres client packages
162
+
163
+
* server.pp: installs the postgres server packages and starts the service; configures the service to accept connections from remote machines, and sets the password for the postgres database user account to ‘postgres’.
164
+
165
+
* postgresql_database.pp: creates a few sample databases with different character sets. Does not create any users for the databases.
166
+
167
+
* postgresql_database\_user.pp: creates a few sample users.
168
+
169
+
* postgresql_database\_grant.pp: shows an example of granting a privilege on a database to a certain user/role.
170
+
171
+
* postgresql_db.pp: creates several test databases, and creates database user accounts with full privileges for each of them.
172
+
173
+
In addition to these manifest-based smoke tests, there are some ruby rspec tests in the spec directory. These tests run against a VirtualBox VM, so they are actually testing the live application of the module on a real, running system. To do this, you must install and setup an [RVM](http://beginrescueend.com/) with [vagrant](http://vagrantup.com/), [sahara](https://github.com/jedi4ever/sahara), and [rspec](http://rspec.info/):
86
174
87
175
$ curl -L get.rvm.io | bash -s stable
88
176
$ rvm install 1.9.3
89
177
$ rvm use --create 1.9.3@puppet-postgresql
90
178
$ gem install vagrant sahara rspec
91
179
92
-
Run the tests like so:
180
+
Run the tests:
93
181
94
182
$ (cd spec; vagrant up)
95
183
$ rspec -f -d -c
96
184
97
-
The test suite will snapshot the VM and rollback between each test.
185
+
The test suite will snapshot the VM and rollback between each test. Next, take a look at the manifests used for the automated tests.
98
186
99
-
Next, take a look at the manifests used for the automated tests.
187
+
$ cat spec/manifests/test_*.pp
100
188
101
-
spec/
102
-
test_module/
103
-
manifests/
104
-
test_*.pp
189
+
Implementation
190
+
---------------
105
191
192
+
### Resource Overview
106
193
107
-
Contributors
194
+
**postgresql**
195
+
196
+
This class is used to manage the basic postgresql client packages (which include the psql command line tool and other utilities).
197
+
198
+
**postgresql::database**
199
+
200
+
This defined type can be used to create a database with no users and no permissions, which is a rare use case.
201
+
202
+
**postgresql_psql**
203
+
204
+
This defined type manages the command line tool for the postgresql module.
205
+
206
+
207
+
### Custom Facts
208
+
209
+
**postgres\_default\_version**
210
+
211
+
The module provides a Facter fact that can be used to determine what the default version of postgres is for your operating system/distribution. Depending on the distribution, it might be 8.1, 8.4, 9.1, or possibly another version. This can be useful in a few cases, like when building path strings for the postgres directories.
212
+
213
+
Limitations
214
+
------------
215
+
216
+
Works with versions of PostgreSQL from 8.1 through 9.2.
217
+
218
+
Development
108
219
------------
109
220
221
+
Puppet Labs modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad of hardware, software, and deployment configurations that Puppet is intended to serve.
222
+
223
+
We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things.
224
+
225
+
You can read the complete module contribution guide [on the Puppet Labs wiki.](http://projects.puppetlabs.com/projects/module-site/wiki/Module_contributing)
226
+
227
+
Disclaimer
228
+
-----------
229
+
230
+
Licensed under the Apache License, Version 2.0 (the "License");
231
+
you may not use this file except in compliance with the License.
232
+
You may obtain a copy of the License at
233
+
234
+
http://www.apache.org/licenses/LICENSE-2.0
235
+
236
+
Unless required by applicable law or agreed to in writing, software
237
+
distributed under the License is distributed on an "AS IS" BASIS,
238
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
239
+
See the License for the specific language governing permissions and
240
+
limitations under the License.
241
+
242
+
Transfer Notice
243
+
----------------
244
+
245
+
This Puppet module was originally authored by Inkling Systems. The maintainer preferred that Puppet Labs take ownership of the module for future improvement and maintenance as Puppet Labs is using it in the PuppetDB module. Existing pull requests and issues were transferred over, please fork and continue to contribute here instead of Inkling.
Licensed under the Apache License, Version 2.0 (the "License");
136
-
you may not use this file except in compliance with the License.
137
-
You may obtain a copy of the License at
279
+
2013-01-16 - Chris Price [email protected] * Fix revoke command in database.pp to support postgres 8.1 (43ded42)
138
280
139
-
http://www.apache.org/licenses/LICENSE-2.0
281
+
2013-01-15 - Jordi Boggiano [email protected] * Add support for ubuntu 12.10 status (3504405)
282
+
283
+
**2.0.0**
284
+
285
+
Notable features:
286
+
287
+
Add support for versions of postgres other than the system default version (which varies depending on OS distro). This includes optional support for automatically managing the package repo for the “official” postgres yum/apt repos. (Major thanks to Etienne Pelletier [email protected] and Ken Barber [email protected] for their tireless efforts and patience on this feature set!) For example usage see tests/official-postgresql-repos.pp.
288
+
289
+
Add some support for Debian Wheezy and Ubuntu Quantal
290
+
291
+
Add new postgres_psql type with a Ruby provider, to replace the old exec-based psql type. This gives us much more flexibility around executing SQL statements and controlling their logging / reports output.
292
+
293
+
Major refactor of the “spec” tests–which are actually more like acceptance tests. We now support testing against multiple OS distros via vagrant, and the framework is in place to allow us to very easily add more distros. Currently testing against Cent6 and Ubuntu 10.04.
294
+
295
+
Fixed a bug that was preventing multiple databases from being owned by the same user (9adcd182f820101f5e4891b9f2ff6278dfad495c - Etienne Pelletier [email protected])
296
+
297
+
Add support for ACLs for finer-grained control of user/interface access (b8389d19ad78b4fb66024897097b4ed7db241930 - dharwood [email protected])
298
+
299
+
Many other bug fixes and improvements!
140
300
141
-
Unless required by applicable law or agreed to in writing, software
142
-
distributed under the License is distributed on an "AS IS" BASIS,
143
-
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
144
-
See the License for the specific language governing permissions and
0 commit comments