Skip to content

Commit 803f9f6

Browse files
committed
docs: postgresql: move installation up as first step
1 parent 5b4d607 commit 803f9f6

File tree

1 file changed

+48
-50
lines changed

1 file changed

+48
-50
lines changed

docs/admin/database/postgresql.md

Lines changed: 48 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,23 @@ The EventDB is a database (usually [PostgreSQL](https://postgresql.org/)) that
99
gets filled with with data from IntelMQ using the SQL Output
1010
Bot.
1111

12-
## intelmq_psql_initdb
12+
## Setup
13+
14+
You have two basic choices to run PostgreSQL:
15+
16+
1. on the same machine as intelmq, then you could use Unix sockets if available on your platform
17+
2. on a different machine. In which case you would need to use a TCP connection and make sure you give the right
18+
connection parameters to each psql or client call.
19+
20+
Make sure to consult your PostgreSQL documentation about how to allow network connections and authentication in case 2.
21+
22+
### PostgreSQL Version
23+
24+
Any supported version of PostgreSQL should work (v>=9.2 as of Oct 2016) [[1]](https://www.postgresql.org/support/versioning/).
25+
26+
If you use PostgreSQL server v >= 9.4, it gives you the possibility to use the time-zone [formatting string](https://www.postgresql.org/docs/9.4/static/images/functions-formatting.html) "OF" for date-times and the [GiST index for the CIDR type](https://www.postgresql.org/docs/9.4/static/images/release-9-4.html#AEN120769). This may be useful depending on how you plan to use the events that this bot writes into the database.
27+
28+
### intelmq_psql_initdb
1329

1430
IntelMQ comes with the `intelmq_psql_initdb` command line tool designed to help with creating the
1531
EventDB. It creates in the first line:
@@ -31,6 +47,36 @@ All elements of the generated SQL file can be adapted and extended before runnin
3147
Be aware that if you create tables using another DB user that is used later by the output bot, you may need to adjust ownership or privileges in the database. If you have problems with database permissions,
3248
refer to `PostgreSQL documentation <https://www.postgresql.org/docs/current/ddl-priv.html>`.
3349

50+
### Installation
51+
52+
Use `intelmq_psql_initdb` to create initial SQL statements from `harmonization.conf`. The script will create the
53+
required table layout and save it as `/tmp/initdb.sql`
54+
55+
You need a PostgreSQL database-user to own the result database. The recommendation is to use the name `intelmq`
56+
. There may already be such a user for the PostgreSQL database-cluster to be used by other bots. (For example from
57+
setting up the expert/certbund_contact bot.)
58+
59+
Therefore if still necessary: create the database-user as postgresql superuser, which usually is done via the system
60+
user `postgres`:
61+
62+
```bash
63+
createuser --no-superuser --no-createrole --no-createdb --encrypted --pwprompt intelmq
64+
```
65+
66+
Create the new database:
67+
68+
```bash
69+
createdb --encoding='utf-8' --owner=intelmq intelmq-events
70+
```
71+
72+
(The encoding parameter should ensure the right encoding on platform where this is not the default.)
73+
74+
Now initialize it as database-user `intelmq` (in this example a network connection to localhost is used, so you would
75+
get to test if the user `intelmq` can authenticate):
76+
77+
```bash
78+
psql -h localhost intelmq-events intelmq </tmp/initdb.sql
79+
```
3480
## EventDB Utilities
3581

3682
Some scripts related to the EventDB are located in the
@@ -181,55 +227,7 @@ The last steps brings us several advantages:
181227
The complete SQL script can be generated using the `intelmq_psql_initdb`. It does *not* cover step 2 to avoid accidental
182228
data loss - you need to do this step manually.
183229

184-
185-
### Other docs
186-
187-
You have two basic choices to run PostgreSQL:
188-
189-
1. on the same machine as intelmq, then you could use Unix sockets if available on your platform
190-
2. on a different machine. In which case you would need to use a TCP connection and make sure you give the right
191-
connection parameters to each psql or client call.
192-
193-
Make sure to consult your PostgreSQL documentation about how to allow network connections and authentication in case 2.
194-
195-
**PostgreSQL Version**
196-
197-
Any supported version of PostgreSQL should work (v>=9.2 as of Oct 2016) [[1]](https://www.postgresql.org/support/versioning/).
198-
199-
If you use PostgreSQL server v >= 9.4, it gives you the possibility to use the time-zone [formatting string](https://www.postgresql.org/docs/9.4/static/images/functions-formatting.html) "OF" for date-times and the [GiST index for the CIDR type](https://www.postgresql.org/docs/9.4/static/images/release-9-4.html#AEN120769). This may be useful depending on how you plan to use the events that this bot writes into the database.
200-
201-
**How to install**
202-
203-
Use `intelmq_psql_initdb` to create initial SQL statements from `harmonization.conf`. The script will create the
204-
required table layout and save it as `/tmp/initdb.sql`
205-
206-
You need a PostgreSQL database-user to own the result database. The recommendation is to use the name `intelmq`
207-
. There may already be such a user for the PostgreSQL database-cluster to be used by other bots. (For example from
208-
setting up the expert/certbund_contact bot.)
209-
210-
Therefore if still necessary: create the database-user as postgresql superuser, which usually is done via the system
211-
user `postgres`:
212-
213-
```bash
214-
createuser --no-superuser --no-createrole --no-createdb --encrypted --pwprompt intelmq
215-
```
216-
217-
Create the new database:
218-
219-
```bash
220-
createdb --encoding='utf-8' --owner=intelmq intelmq-events
221-
```
222-
223-
(The encoding parameter should ensure the right encoding on platform where this is not the default.)
224-
225-
Now initialize it as database-user `intelmq` (in this example a network connection to localhost is used, so you would
226-
get to test if the user `intelmq` can authenticate):
227-
228-
```bash
229-
psql -h localhost intelmq-events intelmq </tmp/initdb.sql
230-
```
231-
232-
**PostgreSQL and null characters**
230+
## PostgreSQL and null characters
233231

234232
While null characters (`0`, not SQL "NULL") in TEXT and JSON/JSONB fields are valid, data containing null characters can
235233
cause troubles in some combinations of clients, servers and each settings. To prevent unhandled errors and data which

0 commit comments

Comments
 (0)