Files @ 10f53ae8f131
Branch filter:

Location: majic-ansible-roles/docs/rolereference.rst

10f53ae8f131 90.3 KiB text/prs.fallenstein.rst Show Annotation Show as Raw Download as Raw
branko
MAR-218: Enable case-sensitive column name handling for database privileges:

- This will become a new default in the next major release of the
community.mysql collection.
- Gets rid of the Ansible mysql_user module warning.
   1
   2
   3
   4
   5
   6
   7
   8
   9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43
  44
  45
  46
  47
  48
  49
  50
  51
  52
  53
  54
  55
  56
  57
  58
  59
  60
  61
  62
  63
  64
  65
  66
  67
  68
  69
  70
  71
  72
  73
  74
  75
  76
  77
  78
  79
  80
  81
  82
  83
  84
  85
  86
  87
  88
  89
  90
  91
  92
  93
  94
  95
  96
  97
  98
  99
 100
 101
 102
 103
 104
 105
 106
 107
 108
 109
 110
 111
 112
 113
 114
 115
 116
 117
 118
 119
 120
 121
 122
 123
 124
 125
 126
 127
 128
 129
 130
 131
 132
 133
 134
 135
 136
 137
 138
 139
 140
 141
 142
 143
 144
 145
 146
 147
 148
 149
 150
 151
 152
 153
 154
 155
 156
 157
 158
 159
 160
 161
 162
 163
 164
 165
 166
 167
 168
 169
 170
 171
 172
 173
 174
 175
 176
 177
 178
 179
 180
 181
 182
 183
 184
 185
 186
 187
 188
 189
 190
 191
 192
 193
 194
 195
 196
 197
 198
 199
 200
 201
 202
 203
 204
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
.. _rolereference:

Role Reference
==============


Common parameters
-----------------

A number of common parameters are used by all of the roles during
deployment. This section lists such parameters.

**enable_backup** (boolean, optional, ``False``)
  If set to ``True``, and the role supports backups, server will be configured
  for back-up of role's data. See role description for more details on what is
  backed-up and if the option is available. Just keep in mind that if you enable
  this globally, all the roles will be running backup-specific tasks. If the
  option has been enabled, the ``backup_client`` role will be included
  automatically (see the role reference for details on parameters that need to
  be provided in the case).


Preseed
-------

The ``preseed`` role can be used for generating simple preseed files for Debian
Wheezy installations.

The generated preseed files allow simplified installation, with a single root
partition. There is a number of parameters that allow for customising the
content of preseed files.

It is possible to specify parameter values that should be used for all servers,
as well for individual servers. It is also possible to combine this approach,
defining global parameters that get overridden per server.

The role will by default process all hosts from the inventory, generating one
preseed file per server.


Parameters
~~~~~~~~~~

**ansible_key** (string, mandatory)
  SSH public key that should be deployed to authorized_keys truststore for
  operating system user ``root``. This is necessary for the bootstrap process
  to work since Debian does not allow password-based logins for root.

**preseed_country** (string, optional, ``SE``)
  Country.

**preseed_directory** (string, mandatory)
  Destination directory where the preseed files should be stored.

  .. warning::
     Do not name this directory ``preseed`` if it lies on a path where Ansible
     would normally look-up the roles (it will conflict with the role name).

**preseed_dns** (string, mandatory if **preseed_network_auto** is ``no``)
  Comma-separated list of DNS servers.

**preseed_domain** (string, mandatory if **preseed_network_auto** is ``no``)
  Server domain.

**preseed_gateway** (string, mandatory if **preseed_network_auto** is ``no``)
  Default gateway for the server.

**preseed_hostname** (string, mandatory if **preseed_network_auto** is ``no``)
  Server hostname.

**preseed_ip** (string, mandatory if **preseed_network_auto** is ``no``)
  IP address for the server network interface.

**preseed_keymap** (string, optional, ``us``)
  Keymap.

**preseed_language** (string, optional, ``en``)
  Language.

**preseed_locale** (string, optional, ``en_US.UTF-8``)
  Locale.

**preseed_mirror_directory** (string, optional, ``/debian``)
  Directory under which the Debian apt repositories can be found on the
  specified mirror.

**preseed_mirror_hostname** (string, optional, ``ftp.se.debian.org``)
  Resolvable hostname of FQDN where the Debian apt repositories can be
  found. Only HTTP mirrors are supported.

**preseed_mirror_proxy** (string, optional, ``None``)
  An HTTP proxy that should be used for accessing the Debian apt
  repositories.

**preseed_netmask** (string, mandatory if **preseed_network_auto** is ``no``)
  Netmask for the server network interface.

**preseed_network_auto** (boolean, optional, ``yes``)
  Specifies whether the network configuration should be automatic (using DHCP)
  or manual. If manual configuration is selected a number of additional options
  needs to be specified: ``preseed_hostname``, ``preseed_domain``,
  ``preseed_ip``, ``preseed_netmask``, ``preseed_gateway``,
  ``preseed_dns``. For some of these values you may want to use per-server
  overrides - see parameter ``preseed_server_overrides``.

**preseed_network_interface** (string, optional, ``eth0``)
  Name of network interface (for example ``eth0``, ``eth1`` etc) that should be
  configured.

**preseed_root_password** (string, optional, ``root``)
  Initial password that should be set for the server during the installation.

**preseed_server_overrides** (string, optional, ``{}``)
  A dictionary consisting out of one or more entries where individual values for
  preseed files can be overridden per-server. Each entry's key should be the
  name of the server, as specified in the inventory. Each value should also be a
  dictionary, where valid keys are: ``country``, ``dns``, ``domain``,
  ``gateway``, ``hostname``, ``ip``, ``keymap``, ``language``, ``locale``,
  ``mirror_directory``, ``mirror_hostname``, ``mirror_proxy``, ``netmask``,
  ``network_auto``, ``network_interface``, ``root_password``,
  ``timezone``. These have the same meaning as their ``preseed_`` counterparts.

**preseed_timezone** (string, optional, ``Europe/Stockholm``)
  Timezone that should be used when calculating server time. It is assumed that
  the local hardware clock is set to UTC.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for a preseed file that sets some global
defaults to be used for all servers, and then overrides it for one server:

.. code-block:: yaml

  ---

  ansible_key: {{ lookup('file', '~/.ssh/id_rsa.pub') }}
  preseed_country: UK
  preseed_directory: /var/www/preseed
  preseed_keymap: UK
  preseed_language: en
  preseed_locale: en_UK.UTF-8
  preseed_mirror_directory: /debian
  preseed_mirror_hostname: ftp.uk.debian.org
  preseed_mirror_proxy: ""
  preseed_network_auto: yes
  preseed_network_interface: eth0
  preseed_root_password: secret
  preseed_timezone: Europe/London
  preseed_server_overrides:
    ldap.example.com:
      network_auto: no
      hostname: ldap
      domain: example.com
      ip: 192.168.1.20
      netmask: 255.255.255.0
      gateway: 192.168.1.1
      dns: 192.168.1.1,192.168.1.2
      timezone: Europe/Stockholm


Bootstrap
---------

The ``bootstrap`` role can be used for bootstraping a new server with
Ansible. In order to apply this role to a server, all that is necessary is root
access to the server (either via SSH or locally).

The role implements the following:

* Installs sudo package.
* Creates operating system user and group for Ansible (``ansible``).
* Sets-up an authorized_key for operating system user ``ansible`` (for remote
  SSH access).
* Configures sudo to allow operating system user ``ansible`` to run sudo
  commands without password authentication.
* Removes the Ansible user's key from the list of authorized keys for user root
  at the end of bootstrap process. This key was necessary only for the bootstrap
  process.


Parameters
~~~~~~~~~~

**ansible_key** (string, mandatory)
  SSH public key that should be deployed to authorized_keys truststore for
  operating system user ``ansible``.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Since the role is meant to be used just after the server has been installed, and
using the ``root`` account, it is probably going to be invoked from a separate
playbook.

For example, a playbook (``bootstrap.yml``) could look something similar to:

.. code-block:: yaml

  ---

  - hosts: "{{ server }}"
    remote_user: root
    roles:
      - bootstrap
    vars:
      ansible_key: "{{ lookup('file', 'authorized_keys/ansible.pub') }}"

With such a playbook in place, it would be invoked with::

  ansible-playbook --ask-pass -e server=test1.example.com bootstrap.yml


Common
------

The ``common`` role can be used for applying a common configuration and
hardening across all servers, no matter what services they provide.

The role implements the following:

* Configures apt to use caching proxy (if any was specified).
* Sets-up umask for all logins to ``0027``.
* Installs sudo.
* Sets-up uniform bash prompt for all accounts (optionally coloured and with
  identifier). This is useful for distinguishing machines and/or environments.
* Sets-up ability to have user-specific ``/etc/profile.d/`` entries via
  ``$HOME/.profile.d/``.
* Installs additional base packages, as configured.
* Disables ``electric-indent-mode`` in Emacs globally if either the ``emacs24``
  or ``emacs24-nox`` are installed through the role.
* Creates additional operating system groups, as configured.
* Creates additional operating system users, as configured.
* Hardens the SSH server by disabling remote ``root`` logins and password-based
  authentication.
* Allows traversing of directory ``/etc/ssl/private/`` to everyone. This lets
  you put TLS private keys in central location where any operating system user
  can reach them provided they have appropriate read/write rights on the file
  itself, and provided they know the exact path of the file.
* Deploys CA certificate files, normally used for truststore purposes, to
  ``/usr/local/share/ca-certificates/``.
* Installs ``ferm`` (for iptables management), configuring a basic firewall
  which allows ICMP echo requests (PING), incoming connection on TCP port 22
  (SSH), and also introduces rate-limitting for incoming ICMP echo request
  pacakges and (new) TCP connections. The rate-limitting is based on the source
  IP address, using the ``iptables hashlimit`` module.
* Sets-up system for performing checks on certificates (currently only if they
  expire within less than 30 days). Roles that want their certificates checked
  should deploy a ``.conf`` to directory ``/etc/check_certificate/`` with paths
  to certificate files, one per line. Certificates are checked on
  daily basis, using crontab (resulting in failures being sent out to
  the ``root`` user).
* Deploys ``apticron`` package that performs checks for available package
  upgrades on daily basis. Mails are delivered to local ``root`` account, and
  can be redirected elsewhere via aliases. If using ``mail_forwarder`` or
  ``mail_server`` roles on the same server, aliases can be set-up through them.
* Sets-up system for performing checks on pip requirements files. Only
  Python 3 is supported. Roles that want their requirements files
  checked should create a sub-directory inside of
  ``/etc/pip_check_requirements_upgrades``, and place ``.txt`` and
  ``.in`` files inside (with same base name). The ``.txt`` files
  should be standard requirements files with fixed versions (the ones
  installed by the role). The ``.in`` files should contain only the
  top-level packages (no dependencies). Avoid hard-coding versions in
  the ``.in`` file unless really needed. For packages where you want
  to stick to stable/LTS version branch, you should be able to use
  ``~=`` operator (for example ``django~=1.8.0``. Checks are
  implemented via `pip-tools <https://github.com/jazzband/pip-tools>`_
  and a custom script that outputs diffs if upgrades are
  available. Script is run via cronjob on daily basis, and any output
  will be delivered to local ``root`` user.
* Optionally configures time synchronisation using NTP (if
  ``ntp_pools`` parameter is set).


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **backup_client**


Backups
~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/log**
  Log files from the system.

**/home**
  Home directory for regular users (this can be changed via role parameters).

**/root**
  Root user's home directory (this can be changed via role parameters).

**/etc/shadow**
  Operating system user passwords.

**/var/mail**
  Local user's mails.

**/var/spool/cron**
  Local user's cronjobs.


Parameters
~~~~~~~~~~

**apt_proxy** (string, optional, ``None``)
  URI of a caching proxy that should be used when retrieving the packages via
  apt.

**os_users** (list, optional, ``[]``)
  A list of operating system users that should be set-up on a server. Each item
  is a dictionary with the following options describing the user parameters:

  **name** (string, mandatory)
    Name of the operating system user that should be created. User's default
    group will have the same name as the user.

  **uid** (number, optional, ``whatever OS picks``)
    UID for the operating system user. User's default group will have a GID
    identical to the user's UID if specified. Otherwise user's default group
    will have OS-determined GID.

  **additional_groups** (list, optional, ``[]``)
    List of additional groups that a user should belong to.

  **authorized_keys** (list, optional, ``[]``)
    List of SSH public keys that should be deployed to user's authorized_keys
    truststore.

  **password** (string, optional, ``!`` - no password)
    Encrypted password that should be set for the user.

**os_groups** (list, optional, ``[]``)
  A list of operating system groups that should be set-up on a server. Each item
  is a dictionary with the following options describing the group parameters:

  **name** (string, mandatory)
    Name of the operating system group that should be created.

  **gid** (number, optional, ``whatever OS picks``)
    GID for the operating system group.

**common_packages** (list, optional, ``[]``)
  List of additional operating system packages that should be installed on the
  server. Each element of the list should be a simple string denoting the name
  of the package.

**ca_certificates** (list, optional, ``{}``)
  Dictionary containing the CA certificates to deploy. Keys are base filenames
  (**without extension**) to be used when placing a certificate file in
  directory ``/usr/local/share/ca-certificates/``, while values are
  corresponding content to be placed in the file.

**extra_backup_patterns** (list, optional, ``[ "/home", "/root" ]]``)
  List of additional globbing patterns defining additional files or directories
  that should be backed-up.

**incoming_connection_limit** (string, optional, ``3/second``)
  Rate at which the incoming ICMP echo-request packages and new TCP connections
  will be accepted at. The value should be specified in the same format as value
  for the ``iptables hashlimit`` option ``--hashlimit-upto``.

**incoming_connection_limit_burst** (string, optional, ``9``)
  Initial burst of packages that should be accepted when the client with
  distinct source IP address connects to the server for the first time (usually
  higher than ``incoming_connection_limit``), even if it would go above the
  specified connection limit.

**maintenance** (boolean, optional, ``False``)
  Specifies if maintenance mode should be enabled or not. In
  maintenance mode incoming TCP connections are allowed only from
  explicitly listed hosts (see ``maintenance_allowed_sources``
  parameter). All ports are covered by this rule, with sole exception
  being the TCP port 22 (SSH). The SSH port is never blocked via
  maintenance mode.

**maintenance_allowed_sources** (list, optional,  ``[]``)
  List of source addreses (IPv4 or IPv6) that should be allowed to
  connect to the server when in maintenance mode. Subnets can be
  specified as well.

**ntp_pools** (list, optional, ``[]``)
  List of NTP pools to use for synchronising the time on managed
  machine using NTP. If no time synchronisation should be set-up, set
  to empty list. Default is not to configure time synchronisation.

  If setting this parameter, it is recommended to set the list of
  pools to list shipped by default Debian configuration::

    - "0.debian.pool.ntp.org"
    - "1.debian.pool.ntp.org"
    - "2.debian.pool.ntp.org"
    - "3.debian.pool.ntp.org"

**pip_check_requirements_in** (list, optional, ``[pip, pip-tools, setuptools, wheel]``)
  List of Python package requirements inputs to use for checking for
  package upgrades for the Python 3 virtual environment used to run
  the check itself.

**pip_check_requirements** (list, optional, ``see below``)
  List of Python package requirements to install in Python 3 virtual
  environment in order to be able to run the ``pip-tools``
  applications as part of pip requirements upgrade checks. This list
  needs to be updated from time to time as the new releases of
  ``pip-tools`` and related packages are coming out.

  Default value is:

  .. code-block:: yaml

    - build==1.0.3
    - click==8.1.7
    - importlib-metadata==6.7.0
    - packaging==23.2
    - pip-tools==6.14.0
    - pip==23.1.2
    - pyproject-hooks==1.0.0
    - setuptools==68.0.0
    - tomli==2.0.1
    - typing-extensions==4.7.1
    - wheel==0.41.3
    - zipp==3.15.0


**pipreqcheck_uid** (integer, optional, ``whatever OS picks``)
  UID for user running the pip requirements upgrade checks. User is created with
  name ``pipreqcheck``.

**pipreqcheck_gid** (integer, optional, ``whatever OS picks``)
  GID for user running the pip requirements upgrade checks. Group is created
  with name ``pipreqcheck``.

**prompt_colour** (string, optional, ``none``)
  Colour for showing the Bash prompt. Supported values are:

  ``black``, ``red``, ``green``, ``brown``, ``blue``, ``purple``, ``cyan``,
  ``light_gray``, ``dark_gray``, ``light_red``, ``light_green``, ``yellow``,
  ``light_blue``, ``light_purple``, ``light_cyan``, ``white``, ``none``.

  You should probably *not* use the ``black`` colour. Setting affects Bash
  shells *only*. Setting the value to ``none`` uses default terminal colour.

**prompt_id** (string, optional, ``NONE``)
  Optional identifier appended to regular Bash prompt, useful for visually
  identifying distinct environments. For example, if set to ``test``, resulting
  prompt will be similar to ``admin@web[test]:~$``. Setting affects Bash shells
  *only*.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up some common users, groups, and
packages on all servers:

.. code-block:: yaml

  ---

  os_users:
    - name: admin
      uid: 1000
      additional_groups:
        - sudo
      authorized_keys:
        - "{{ lookup('file', '/home/admin/.ssh/id_rsa.pub') }}"
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'
    - name: john
      uid: 1001
      password: '$6$AaJRWtqyX5pk$IP8DUjgY0y2zqMom9BAc.O9qHoQWLFCmEsPRCika6l/Xh87cp2SnlMywH0.r4uEcbHnoicQG46V9VrJ8fxp2d.'

  os_groups:
    - name: localusers
      gid: 2500

  common_packages:
    - emacs23-nox
    - screen
    - debconf-utils

  ca_certificates:
    "truststore": "{{ lookup('file', '../certs/truststore.pem') }}"

  incoming_connection_limit: 2/second

  incoming_connection_limit_burst: 6

  prompt_colour: light_green

  prompt_id: PROD

.. _ldap_client:

LDAP Client
-----------

The ``ldap_client`` role can be used for setting-up an OpenLDAP client on
destination machine.

The role implements the following:

* Installs OpenLDAP client tools.
* Sets-up global configuration file for OpenLDAP clients at /etc/ldap/ldap.conf.


Parameters
~~~~~~~~~~

**ldap_client_config** (list, optional, ``[]``)
  A list of configuration options that should be put into the LDAP configuration
  file. Each item is a dictionary with the following options defining the
  configuration parameter:

  **comment** (string, mandatory)
    Comment that will be shown in the file just above the configuration option.

  **option** (string, mandatory)
    Name of configuration option.

  **value** (string, mandatory)
    Value for configuration option.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting some common LDAP client options:

.. code-block:: yaml

  ---

  ldap_client_config:
    - comment: Set the base DN
      option: BASE
      value: dc=example,dc=com
    - comment: Set the default URI
      option: URI
      value: ldap://ldap.example.com/
    - comment: Set the truststore for TLS/SSL
      option: TLS_CACERT
      value: /etc/ssl/certs/example_ca.pem
    - commment: Force basic server certificate verification
      option: TLS_REQCERT
      value: demand
    - comment: Disable CRL checks for server certificate
      option: TLS_CRLCHECK
      value: none


LDAP Server
-----------

The ``ldap_server`` role can be used for setting-up an OpenLDAP server on
destination machine.

The role implements the following:

* Deploys LDAP TLS private key and certificate.
* Configures TLS versions and ciphers suppported by the server.
* Installs OpenLDAP server (package ``slapd``).
* Configures OpenLDAP server (base DN - domain, organisation, TLS, SSF, log levels).
* Enables the ``misc`` LDAP schema (from ``/etc/ldap/schema/misc.ldif``). This
  is necessary for the mail server role.
* Enables the ``memberof`` overlay on top of default database. The overlay is
  configured to keep track of membership changes for object class
  ``groupOfUniqueNames`` via attribute ``uniqueMember``. Enforcement of
  referential integrity is turned on as well (modifications of ``memberof``
  attribute will update corresponding group as well.
* Creates a basic directory structure used by most of the other roles.
* Creates a basic directory structure used by the mail server role.
* Creates login entries for services that need to consume LDAP directory data in
  some way.
* Creates user-supplied groups in LDAP.
* Configures permissions.
* Creates LDAP entries.
* Configures firewall to allow incoming connections to the LDAP server (via both
  TCP 389 and 636).
* Sets the LDAP server administrator's password.


LDIF Templates
~~~~~~~~~~~~~~

For adding users, use::

  dn: uid=USERNAME,ou=people,BASE_DN
  objectClass: inetOrgPerson
  objectClass: simpleSecurityObject
  uid: USERNAME
  userPassword: PASSWORD_FROM_SLAPPASSWD
  cn: NAME SURNAME
  sn: SURNAME
  gn: NAME
  displayName: DISPLAYNAME
  initials: INITIALS
  mail: MAIL
  mobile: MOBILE



Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**
* **ldap_client**
* **backup_client**


Backups
~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/srv/backup/slapd.bak**
  Dump of the LDAP database. LDAP database dump is created every day at 01:45 in
  the morning. This does *not* include the dump of the config database
  (``cn=config``).


Parameters
~~~~~~~~~~

**ldap_admin_password** (string, mandatory)
  Password for the default administrator account of LDAP server (the
  ``cn=admin,DOMAIN`` entry/user).

**ldap_entries** (list, optional, ``[]``)
  List of entries that should be kept in the LDAP directory. Each item is a
  dictionary describing a single LDAP entry with the following keys:

  **dn** (string, mandatory)
    LDAP DN entry.

  **state** (string, optional, ``present``)
    Whether the entry should be present or not. Value can be anything
    supported by the ``ldap_entry`` module. Keep in mind that state
    ``present`` will not update the attributes and their values if the
    entry is already present.

  **attributes** (dictionary, mandatory)
    Dictionary describing remaining attributes (except ``dn``). The keys in this
    dictionary should be the attribute names. The values should be either
    strings, for setting a single attribute value, or a list of strings if it is
    necessary to set multiple values for the same attribute.

**ldap_permissions** (list, optional, ``see below``)
  List of LDAP access rules to apply to base DN served by the LDAP server. The
  listed access control rules will *replace* all existing rules, and will be
  added in the same order they are listed in. Each item is a string that
  constitutes a single access control rule. The format should be the same as
  described in `OpenLDAP Administrator's Guide
  <http://www.openldap.org/doc/admin24/access-control.html#Access%20Control%20via%20Dynamic%20Configuration>`.

  Default value is:

  .. code-block:: yaml

    - >
      to *
      by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage
      by * break
    - >
      to attrs=userPassword,shadowLastChange
      by self write
      by anonymous auth
      by dn="cn=admin,BASEDN" write
      by * none
    - >
      to dn.base=""
      by * read
    - >
      to *
      by self write
      by dn="cn=admin,BASEDN" write
      by * none

**ldap_server_consumers** (list, optional, ``[]``)
  List of items describing additional login entries that should be created for
  services that want to be able to log-in into the LDAP server and consume the
  data present within. Each item should be a dictionary, with the following keys
  avaialable:

  - **name** (name of the service, mandatory, this will be used to construct the
    login entry DN in format of ``cn=NAME,ou=services,BASE_DN``)
  - **password** (password for the login entry, mandatory)
  - **state** (state of the service, optional, defaults to ``present``, this
    should be ``present`` or ``absent``, allowing for removal of old services)

**ldap_server_groups** (list, optional, ``[]``)
  List of groups that should be created in the LDAP directory. Each item should
  be a dictionary containing the following keys:

  - **name** (name of the group, mandatory, this will be used to construct the
    group DN in format of ``cn=NAME,ou=groups,BASE_DN``)
  - **state** (state of the group, optional, defaults to ``present``, this
    should be ``present`` or ``absent``, allowing for removal of old groups)

**ldap_server_domain** (string, mandatory)
  Domain that should be used for constructing the base DN of default user LDAP
  database. This should be a sub-domain dedicated to organisation. The base DN
  will be constructed by putting all elements of the sub-domain as ``dc``
  entries (as per standard Debian convention). E.g. ``example.com`` would get
  transformed into ``dc=example,dc=com``.

**ldap_server_organization** (string, optional, ``Private``)
  Organization that should be specified in the base DN entry.

**ldap_server_log_level** (string, optional, ``256``)
  Log level to use for the server. This should be compatible with OpenLDAP
  configuration option ``olcLogLevel``. See `OpenLDAP Administrator's Guide
  <http://www.openldap.org/doc/admin24/slapdconf2.html#cn=config>` for value
  description and syntax.

**ldap_server_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for LDAP service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_ldap.pem``.

**ldap_server_tls_key** (string, mandatory)
  Private key used for TLS for LDAP service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_ldap.key``.

**ldap_server_ssf** (number, optional, ``128``)
  Minimum *Security Strength Factor* to require from all incoming
  connections. This applies for both remote and local connections.

**ldap_tls_ciphers** (string, optional ``NONE:+VERS-TLS1.2:+CTYPE-X509:+COMP-NULL:+SIGN-RSA-SHA256:+SIGN-RSA-SHA384:+SIGN-RSA-SHA512:+DHE-RSA:+ECDHE-RSA:+SHA256:+SHA384:+SHA512:+AEAD:+AES-128-GCM:+AES-256-GCM:+CHACHA20-POLY1305:+CURVE-ALL``)

  .. warning::
     Under Debian Bullseye and upwards, slapd does not use the DH
     parameters generated by the role, but instead uses them to pick
     one of the recommended DH parameters from `RFC-7919
     <https://www.ietf.org/rfc/rfc7919.txt>`_. This is based on the
     size of role-generated parameters.

  TLS ciphers to enable on the LDAP server. This should be a GnuTLS-compatible
  cipher specification that should also include what TLS protocol versions
  should be used. Value should be compatible with OpenLDAP server option
  ``olcTLSCipherSuite``. Default value allows only TLSv1.2 and strong PFS
  ciphers.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up LDAP server:

.. code-block:: yaml

  ---

  ldap_server_domain: "example.com"
  ldap_server_organization: "Example Corporation"
  ldap_server_log_level: 256
  ldap_server_tls_certificate: "{{ lookup('file', '~/tls/ldap.example.com_ldap.pem') }}"
  ldap_server_tls_key: "{{ lookup('file', '~/tls/ldap.example.com_ldap.key') }}"
  ldap_server_ssf: 128

  ldap_permissions:
    - >
      to *
      by dn.exact=gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth manage
      by * break
    - >
      to attrs=userPassword,shadowLastChange
      by self write
      by anonymous auth
      by dn="cn=admin,dc=example,dc=com" write
      by * none
    - >
      to dn.base=""
      by * read
    - >
      to *
      by self write
      by dn="cn=admin,dc=example,dc=com" write
      by users read
      by * none

  ldap_entries:
    - dn: ou=people,dc=example,dc=com
      attributes:
        objectClass: organizationalUnit
        ou: people
    - dn: ou=groups,dc=example,dc=com
      attributes:
        objectClass: organizationalUnit
        ou: groups
    - dn: uid=john,dc=example,dc=com
      attributes:
        objectClass:
          - inetOrgPerson
          - simpleSecurityObject
        userPassword: somepassword
        uid: john
        cn: John Doe
        sn: Doe


XMPP Server
-----------

The ``xmpp_server`` role can be used for setting-up Prosody, an XMPP server, on
destination machine.

The role implements the following:

* Deploys XMPP TLS private key and certificate.

  .. warning::
     The issued certificate must have multiple FQDNs listed as subject
     alternative names (DNS names) for each configured domain:

     - domain itself
     - ``conference.DOMAIN``
     - ``proxy.DOMAIN``

     A daily cron job is run to validate that all certificates have
     been configured and issued correctly.

* Installs Prosody.
* Configures Prosody.
* Configures firewall to allow incoming connections to the XMPP server.

Prosody is configured as follows:

* Modules enabled: roster, saslauth, tls, dialback, posix, private, vcard,
  version, uptime, time, ping, pep, register, admin_adhoc, announce,
  legacyauth, carbons, mam.
* Self-registration is not allowed.
* TLS is configured. Legacy TLS is available on port 5223.
* Client-to-server communication requires encryption (TLS).
* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for
  incoming connections.
* Configures TLS versions and ciphers supported by Prosody (for
  *c2s*/client connections only).
* Authentication is done via LDAP. For setting the LDAP TLS truststore, see
  :ref:`LDAP Client <ldap_client>`.
* Internal storage is used.
* For each domain specified, a dedicated conference/multi-user chat (MUC)
  service is set-up, with FQDN set to ``conference.DOMAIN``.
* For each domain specified, a dedicated file proxy service will be set-up, with
  FQDN set to ``proxy.DOMAIN``.

Prosody expects a specific directory structure in LDAP when doing look-ups:

* Prosody will log-in to LDAP as user
  ``cn=prosody,ou=services,XMPP_LDAP_BASE_DN``.
* User entries are read from sub-tree (first-level only)
  ``ou=people,XMPP_LDAP_BASE_DN``. Query filter used for finding users is
  ``(&(mail=$user@$host)(memberOf=cn=xmpp,ou=groups,XMPP_LDAP_BASE_DN))``. This
  allows group-based granting of XMPP service to users.


LDIF Templates
~~~~~~~~~~~~~~

For adding user to a group, use::

  dn: cn=xmpp,ou=groups,BASE_DN
  changetype: modify
  add: uniqueMember
  uniqueMember: uid=USERNAME,ou=people,BASE_DN


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**
* **backup_client**


Backups
~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/lib/prosody/**
  Roster information, as well as undelivered (offline) messages for all XMPP
  users. Keep in mind that list of available users and their credentials are
  stored in the LDAP directory (which is backed-up via LDAP server role).


Parameters
~~~~~~~~~~

**xmpp_administrators** (list, mandatory)
  List of Prosody users that should be granted administrator privileges over
  Prosody. Each item is a string with value equal to XMPP user ID
  (i.e. ``john.doe@example.com``).

**xmpp_domains** (list, mandatory)
  List of domains that are served by this Prosody instance. Each item is a
  string specifying a domain.

**xmpp_ldap_base_dn** (string, mandatory)
  Base DN on the LDAP server. A specific directory structure is expected under
  this entry (as explained above) in order to locate the available domains,
  users, aliases etc.

**xmpp_ldap_password** (string, mandatory)
  Password used for authenticating to the LDAP server.

**xmpp_ldap_server** (string, mandatory)
  Fully qualified domain name, hostname, or IP address of the LDAP server used
  for user authentication and listing.

**xmpp_server_archive_expiration** (string, optional, ``never``)
  Expiration period for messages stored server-side using `XEP-0313:
  Message Archive Management
  <https://xmpp.org/extensions/xep-0313.html>`_. The value should be
  compatible with `Prosody mod_mam
  <https://prosody.im/doc/modules/mod_mam>`_ configuration option
  ``archive_expires_after``.

**xmpp_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``)
  TLS ciphers to enable on the XMPP server. This should be an
  OpenSSL-compatible cipher specification. Value should be compatible
  with Prosody's option ``ciphers`` normally defined within the
  ``ssl`` section of configuration file (see `official documentation
  <https://prosody.im/doc/advanced_ssl_config#ciphers>`_ for details).
  Default value allows only TLSv1.2 and strong PFS ciphers with RSA
  private keys.

**xmpp_server_tls_protocol** (string, optional, ``tlsv1_2+``)
  Protocol version the XMPP server should support for client
  connections. The value specified should be compatible with Prosody's
  ``protocol`` option normally defined within the ``ssl`` section of
  configuration file (see `official documentation
  <https://prosody.im/doc/advanced_ssl_config#protocol>`__ for
  details).

**xmpp_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for XMPP service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_xmpp.pem``.

**xmpp_tls_key** (string, mandatory)
  Private key used for TLS for XMPP service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_xmpp.key``.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

  xmpp_administrators:
    - john.doe@example.com
  xmpp_domains:
    - example.com
  xmpp_ldap_base_dn: dc=example,dc=com
  xmpp_ldap_password: xmpp
  xmpp_ldap_server: ldap.example.com
  # These are default key and certificate that generated during Prosody
  # installation. Possibly you want to deploy your own.
  xmpp_tls_key: "{{ lookup('file', '/etc/prosody/certs/localhost.key') }}"
  xmpp_tls_certificate: "{{ lookup('file', '/etc/prosody/certs/localhost.crt') }}"


Mail Server
-----------

.. warning::
   It may happen that the ``clamav-freshclam`` service hasn't finished
   downloading the virus database before the ``clamav-daemon`` and
   ``clamav-milter`` services are enabled during the initial run. If mail server
   is not operational, you may need to wait for a little while for download to
   finish, and then restart the ``clamav-daemon`` and ``clamav-milter``
   services.

The ``mail_server`` role can be used for setting-up a complete mail server
solution, which includes both SMTP and IMAP service, on destination machine.

Postfix is used SMTP, while Dovecot is used for IMAP.

The role implements the following:

* Installs rsync.
* Deploys IMAP/SMTP TLS private keys and certificates.
* Installs and configures Dovecot, Postfix, ClamAV, and ClamAV Milter.
* Purges Exim4 configuration (just in case).
* Sets-up aliases for the local recipients.
* Installs SWAKS (utility for testing SMTP servers).
* Sets-up the necessary directories and files under Postfix chroot.
* Configures firewall to allow incoming connections to the mail server. This
  includes set-up of redirection from TCP port 26 to TCP port 587 (alternate
  submission port), as well as redirection from TCP port 27 to TCP port 25
  (alternate SMTP port), useful as workaround for ISP/hotel blocks.

Deployed services are configured as follows:

* Both Postfix and Dovecot look-up available domains, users, and aliases in
  LDAP.
* Incoming and outgoing mail is scanned with ClamAV (via ClamAV
  Milter). Infected mails are rejected.
* Mail is stored in directory ``/var/MAIL_USER/DOMAIN/USER``, using ``Maildir``
  format.
* TLS is required for user log-ins for both SMTP and IMAP.
* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for
  incoming connections.
* For user submission (SMTP), users must connect and authenticate over TCP
  port 587.
* Configures TLS versions and ciphers supported by Dovecot.
* Configures TLS versions and ciphers supported by Postfix on submission port
  (587). TLS configuration on port 25 is kept intact in order to maintain maximum
  interoperability with other servers.
* RBL's are used for combating spam (if any is specified in configuration, see
  below).
* Postfix is configured to deliver undeliverable bounces to postmaster. This
  helps with detecting misconfigured applications and servers.
* Postfix is configured to prevent forging of sender addresses for
  logged-in users. Logged-in users can use either their own e-mail as
  sender, or one of the aliases associated with their e-mail.

Both Postfix and Dovecot expect a specific directory structure in LDAP when
doing look-ups:

* Postfix will log-in to LDAP as user
  ``cn=postfix,ou=services,MAIL_LDAP_BASE_DN``.
* Dovecot will log-in to LDAP as user
  ``cn=dovecot,ou=services,MAIL_LDAP_BASE_DN``.
* Domain entries need to be available as
  ``dc=DOMAIN,ou=domains,ou=mail,ou=services,MAIL_LDAP_BASE_DN``.
* Alias entries need to be available as
  ``cn=ALIAS,ou=aliases,ou=mail,ou=services,MAIL_LDAP_BASE_DN``.
* User entries are read from sub-tree (first-level only)
  ``ou=people,MAIL_LDAP_BASE_DN``. Query filter used for finding users is
  ``(&(mail=%s)(memberOf=cn=mail,ou=groups,MAIL_LDAP_BASE_DN))``. This allows
  group-based granting of mail services to users.


LDIF Templates
~~~~~~~~~~~~~~

For adding domains, use::

  dn: dc=DOMAIN,ou=domains,ou=mail,ou=services,BASE_DN
  objectClass: dNSDomain
  dc: DOMAIN

For adding aliases, use::

  dn: cn=ALIAS,ou=aliases,ou=mail,ou=services,BASE_DN
  objectClass: nisMailAlias
  cn: ALIAS
  rfc822MailMember: REALEMAIL

For adding user to a group, use::

  dn: cn=mail,ou=groups,BASE_DN
  changetype: modify
  add: uniqueMember
  uniqueMember: uid=USERNAME,ou=people,BASE_DN


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**
* **backup_client**


Backups
~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/var/{{ mail_user }}**
  All data stored by the mail server, including mails and Sieve scripts. Keep in
  mind that list of available users and their credentials are stored in the LDAP
  directory (which is backed-up via LDAP server role).


Parameters
~~~~~~~~~~

**mail_ldap_base_dn** (string, mandatory)
  Base DN on the LDAP server. A specific directory structure is expected under
  this entry (as explained above) in order to locate the available domains,
  users, aliases etc.

**mail_ldap_url** (string, mandatory)
  LDAP URL that should be used for connecting to the LDAP server for doing
  domain/user look-ups.

**mail_ldap_tls_truststore** (string, mandatory)
  X.509 certificate chain used for issuing certificate for the LDAP service. The
  file will be stored in locations ``/etc/ssl/certs/mail_ldap_tls_truststore.pem``
  and ``/var/spool/postfix/etc/ssl/certs/mail_ldap_tls_truststore.pem``.

**mail_ldap_postfix_password** (string, mandatory)
  Password for authenticating the Postfix LDAP user.

**mail_ldap_dovecot_password** (string, mandatory)
  Password for authenticating the Dovecot LDAP user.

**mail_message_size_limit** (integer, optional, ``10240000``)
  Maximum size of message in bytes that the SMTP server should accept
  for incoming mails. If the mail message size exceeds the listed
  value, it will be rejected by the server. The size is also
  advertised as part of SMTP server capabilities (in response to the
  ``ehlo`` SMTP command).

**mail_server_minimum_tls_protocol** (string, optional, ``"TLSv1.2"``)
  Minimum version of TLS protocol to allow when connecting to SMTP
  submission port or IMAP. Value should be compatible with Dovecot's
  ``ssl_protocols`` configuration option.

**mail_server_smtp_additional_configuration** (string, optional, ``""``))
  Additional configuration directives to include in SMTP server main
  configuration file. Directives must be specifically compatible with
  Postfix, and are treated verbatim (multi-line string will suffice).

**mail_server_tls_ciphers** (string, optional ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``)
  TLS ciphers to enable on the mail server (for IMAP and SMTP submission). This
  should be an OpenSSL-compatible cipher specification. Value should be
  compatible with Postfix configuration option ``tls_high_cipherlist`` and
  Dovecot configuration option ``ssl_cipher_list``. Default value allows only
  TLSv1.2 and strong PFS ciphers.

**mail_user** (string, optional, ``vmail``)
  Name of the user that owns all the mail files.

**mail_user_uid** (integer, optional, ``whatever OS picks``)
  UID of the user that owns all the mail files.

**mail_user_gid** (integer, optional, ``whatever OS picks``)
  GID of the user that owns all the mail files.

**imap_max_user_connections_per_ip** (integer, optional, ``10``)
  Maximum number of IMAP connections from a single IP for a single user. Default
  value can be considered rather low, since two devices (computer and phone)
  will easily reach it.

**imap_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for IMAP service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_imap.pem``.

**imap_tls_key** (string, mandatory)
  Private key used for TLS for IMAP service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_imap.key``.

**local_mail_aliases** (dictionary, optional, ``{}``)
  Dictionary defining the local aliases. Aliases defined this way will either be
  appended to default aliases on the server, or replace the existing entries (if
  the alias/recipient is already present). Keys in the dictionary are the local
  recipients/aliases, while the value provided should be a space-separated list
  of mail addresses (or local users) where the mails should be forwarded.

**smtp_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for SMTP service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_smtp.pem``.

**smtp_tls_key** (string, mandatory)
  Private key used for TLS for SMTP service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_smtp.key``.

**imap_folder_separator** (string, optional, ``/``)
  Character used for separating the IMAP folders when clients are requesting
  listing from the server. Usually either slash(``/``) or dot(``.``).

**smtp_rbl** (list, optional, ``[]``)
  List of RBLs to use for detecting servers which send out spam. Each item is a
  string resembling the RBL domain.

**mail_postmaster** (string, optional, ``postmaster@{{ ansible_domain}}``)
  Mail address to use for the postmaster account in Dovecot.

**smtp_allow_relay_from** (list, optional, [])
  List of networks from which mail relaying is allowed even without
  authentication. Each item in the list is a string defining a network. The
  format must be compatible with Postfix ``mynetworks`` setting (for example:
  ``192.168.1.0/24``, ``myhost.example.com`` etc).


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up XMPP server using Prosody:

.. code-block:: yaml

  ---

  mail_ldap_url: ldap://ldap.example.com/
  mail_ldap_tls_truststore: /etc/ssl/certs/truststore.pem
  mail_ldap_base_dn: dc=example,dc=com
  mail_ldap_postfix_password: postfix
  mail_ldap_dovecot_password: dovecot

  mail_user: vmail
  mail_user_uid: 5000
  mail_user_gid: 5000

  # All mails sent to local user root will be forwarded to external account as
  # well.
  local_mail_aliases:
    root: "root john.doe@example.com"

  imap_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_imap.pem') }}"
  imap_tls_key: "{{ lookup('file', '~/tls/mail.example.com_imap.key') }}"
  smtp_tls_certificate: "{{ lookup('file', '~/tls/mail.example.com_smtp.pem') }}"
  smtp_tls_key: "{{ lookup('file', '~/tls/mail.example.com_smtp.key') }}"
  imap_folder_separator: /
  smtp_rbl:
    - bl.spamcop.net
    - zen.spamhaus.org
  mail_postmaster: postmaster@example.com

  smtp_allow_relay_from:
    - ldap.example.com
    - xmpp.example.com

  imap_max_user_connections_per_ip: 50


Mail Forwarder
--------------

The ``mail_forwarder`` role can be used for setting-up a local SMTP server for
sending out mails and receiving mails for local users. The SMTP server is
provided by Postfix.

SMTP service on server set-up this way is not meant to be exposed to the
Internet directly, and should receive delivery failures from the relay server
instead.

The role implements the following:

* Installs and configures Postfix.
* Purges Exim4 configuration (just in case).
* Sets-up aliases for the local recipients.
* Installs SWAKS (utility for testing SMTP servers).
* Configures firewall to accept SMTP connections from SMTP relay (if
  one has been configured). This allows for delivery of bounced
  e-mails.

  .. note::
     Firewall rules are based on IPv4 and IPv6 addresses resolved via
     managed server at time of deployment. If the SMTP relay changes
     its IP addresess, this role needs to be reapplied against the
     managed machines.

Postfix is configured as follows:

* Local destinations are set-up.
* A relay host is set.
* TLS is enforced for relaying mails, with configurable truststore for server
  certificate verification if SMTP relay is used. If SMTP relay is not used
  (configured), no certificate verification is done.
* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for
  incoming connections.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**


Parameters
~~~~~~~~~~

**local_mail_aliases** (dictionary, optional, ``[]``)
  Dictionary defining the local aliases. Aliases defined this way will either be
  appended to default aliases on the server, or replace the existing entries (if
  the alias/recipient is already present). Keys in the dictionary are the local
  recipients/aliases, while the value provided should be a space-separated list
  of mail addresses (or local users) where the mails should be forwarded.

**mail_message_size_limit** (integer, optional, ``10240000``)
  Maximum size of message in bytes that the SMTP server should accept
  for incoming mails. If the mail message size exceeds the listed
  value, it will be rejected by the server. The size is also
  advertised as part of SMTP server capabilities (in response to the
  ``ehlo`` SMTP command). Changing the value is primarily useful when
  SMTP from relay is allowed (via the ``smtp_from_relay_allowed``
  parameter), since incoming SMTP communication is otherwise not
  allowed at all.

**smtp_from_relay_allowed** (boolean, optional, ``True``)
  Specify if SMTP traffic from SMTP relay should be allowed or not (for bounced
  messages, for example). This parameter should be set to ``False`` on systems
  behind NAT or on systems that may not have constant network connectivity (such
  as laptops) to avoid firewall failures since SMTP relay name needs to be
  resolvable.

**smtp_relay_host** (string, optional, ``None``)
  SMTP server via which the mails are sent out for non-local recipients.

**smtp_relay_host_port** (integer, optional, ``None``)
  Port to use when connecting to the SMTP relay host.

**smtp_relay_truststore** (string, mandatory)
  X.509 certificate chain used for issuing certificate for the SMTP relay
  service. The file will be stored in location
  ``/etc/ssl/certs/smtp_relay_truststore.pem``


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up the mail forwarder:

.. code-block:: yaml

  ---

  # All mails sent to local user root will be forwarded to external account as
  # well.
  local_mail_aliases:
    root: "root john.doe@example.com"

  smtp_relay_host: mail.example.com

  smtp_relay_host_port: 27

  smtp_from_relay_allowed: False

  smtp_relay_truststore: /etc/ssl/certs/example_ca_chain.pem


Web Server
----------

The ``web_server`` role can be used for setting-up a web server on destination
machine.

The role is supposed to be very lightweight, providing a basis for deployment of
web applications.

The role implements the following:

* Installs and configures nginx with a single, default vhost with a small static
  index page.
* Deploys the HTTPS TLS private key and certificate (for default vhost).
* Configures TLS versions and ciphers supported by Nginx.
* Uses 2048-bit Diffie-Hellman parameters for relevant TLS ciphers for
  incoming connections.
* Configures firewall to allow incoming connections to the web server.
* Installs and configures virtualenv and virtualenvwrapper as a common base for
  Python apps.
* Installs and configures PHP FPM as a common base for PHP apps.

The web server is configured as follows:

* No plaintext HTTP is allowed, HTTPS is mandatory. Clients connecting
  via plaintext HTTP are redirected to HTTPS.
* Clients are served with ``Strict-Transport-Security`` header with
  value of ``max-age=31536000; includeSubDomains``. This forces
  compliant clients to always connect using HTTPS to the web server
  when accessing its default domain, as well as any subdomains served
  by this web server or any other. The (client-side) cached header
  value expires after one year.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**


Parameters
~~~~~~~~~~

**default_https_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ ansible_fqdn }}_https.pem``.

**default_https_tls_key** (string, mandatory)
  Private key used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ ansible_fqdn }}_https.key``.

**environment_indicator** (dictionary, optional, ``null``)
  Specify configuration for including environment indicator on all
  HTML pages. Indicator is a simple strip at bottom of a page with
  custom background colour, text colour, and text. Indicator can be
  collapsed by clicking on the arrows on the left side of the strip.

  Specifying environment indicator is useful for avoiding mistakes
  when testing by having better visibility what environment you are in
  (production/staging/test).

  The following keys need to be specified:

  **background_colour** (string, mandatory)
    Background colour to use for the strip at bottom. This should be value
    compatible with CSS ``background-color`` attribute.

  **text_colour** (string, mandatory)
    Text colour to use for the strip at bottom. This should be value compatible
    with CSS ``color`` attribute.

  **text** (string, mandatory)
    Text to show in show in the strip at bottom.

**web_default_title** (string, optional, ``Welcome``)
  Title for the default web page shown to users (if no other vhosts were matched).

**web_default_message** (string, optional, ``You are attempting to access the web server using a wrong name or an IP address. Please check your URL.``)
  Message for the default web page shown to users (if no other vhosts were
  matched).

**web_server_tls_protocols** (list, optional, ``[ "TLSv1.2" ]``)
  List of TLS protocols the web server should support. Each value specified
  should be compatible with Nginx configuration option ``ssl_protocols``.

**web_server_tls_ciphers** (string, optional, ``DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:DHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:!aNULL:!MD5:!EXPORT``)
  TLS ciphers to enable on the web server. This should be an OpenSSL-compatible
  cipher specification. Value should be compatible with Nginx configuration
  option ``ssl_ciphers``. Default value allows only TLSv1.2 and strong PFS
  ciphers with RSA private keys.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up web server:

.. code-block:: yaml

  ---

  default_https_tls_key: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.key') }}"
  default_https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/web.example.com_https.pem') }}"

  web_default_title: "Welcome to Example Inc."
  web_default_message: "You are attempting to access the web server using a wrong name or an IP address. Please check your URL."


PHP Website
-----------

The ``php_website`` role can be used for setting-up a website powered by PHP on
destination machine.

This role is normally not supposed to be used directly, but should instead serve
as the basis for writing website-specific roles. Therefore the role is written
in quite generic way, allowing the integrator to write his/her own logic for
deploying the necessary PHP applications, while still reusing a common base and
reducing the workload.

The role implements the following:

* Creates a dedicated user/group for running the PHP scripts.
* Creates a dedicated administrator user for maintaining the website.
* Creates a base directory where the website-specific code and data should be
  stored at.
* Adds nginx to website's group, so nginx could read the necessary files.
* Adds website administrator to website's group, so administrator could manage
  the code and data.
* Installs additional packages required for running the role (as configured).
* Deploys the HTTPS TLS private key and certificate (for website vhost).
* Configures PHP FPM and nginx to serve the website.

The role is implemented with the following layout/logic in mind:

* Clients are served with ``Strict-Transport-Security`` header with
  value of ``max-age=31536000; includeSubDomains``. This forces
  compliant clients to always connect using HTTPS to the web server
  when accessing its domain, as well as any subdomains served
  by this web server or any other. The (client-side) cached header
  value expires after one year.
* Website users are named after the ``FQDN`` (fully qualified domain name) of
  website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to
  ``FQDN`` where dots have been replaced by underscores (for example,
  ``web-cloud_example_com``).
* Website users are set-up via GECOS field to have their umask set to ``0007``
  (in combination with ``pam_umask``).
* Administrator users are named after the ``FQDN`` (fully qualified domain name)
  of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal
  to ``FQDN`` where dots have been replaced by underscores (for example,
  ``admin-cloud_example_com``).
* All websites reside within a dedicated sub-directory in ``/var/www``. The
  sub-directory name is equal to the ``FQDN`` used for accessing the
  website. Owner of the directory is set to be the application administrator,
  while group is set to be the website group. Additionally, ``SGID`` bit is set
  on the directory. This allows admin, with correct umask, to create necessary
  files and directories that should be readable (and eventually writeable) by
  the website user (running the PHP scripts) without having to become root.
* All files placed in the website directory should be either created there
  directly, or copied to the directory in order to make sure the ``SGID`` gets
  honored. **Do not move the files, the permissions will not be set correctly.**
* Within the website directory, nginx/php5-fpm will expect to find the relevant
  files within the htdocs sub-directory (this can be symlink too).
* nginx communicates with PHP FPM over a dedicated Unix socket for each website.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**
* **web_server**


Parameters
~~~~~~~~~~

**additional_fpm_config** (dict, optional, ``{}``)
  Additional PHP FPM configuration options that should be included for PHP
  website's pool. Keys are parameter names, values are associated values. Don't
  forget to include quotes in the value itself if expected value type is string.

**additional_nginx_config** (list, optional, ``[]``)
  List providing additional Nginx configuration options to include. This can be
  useful for specifying things like error pages. Options are applied inside of a
  **server** context of Nginx configuration file.

  Each item is a dictionary with the following options describing the extra
  configuration option:

  **comment** (string, mandatory)
    Comment describing the configuration option.

  **value** (string, mandatory)
    Configuration option.

**admin_uid** (integer, optional, ``whatever OS picks``)
  UID of the dedicated website administrator user. The user will be member of
  website group.

**deny_files_regex** (list, optional, ``[]``)
  List of regular expressions for matching files/locations to which the web
  server should deny access. This is useful to block access to any sensitive
  files that should not be served directly by the web server. The format must be
  compatible with regular expressions used by ``nginx`` for ``location ~``
  syntax.

**environment_indicator** (dictionary, optional, ``null``)
  Specify configuration for including environment indicator on all
  HTML pages. Indicator is a simple strip at bottom of a page with
  custom background colour, text colour, and text. Indicator can be
  collapsed by clicking on the arrows on the left side of the strip.

  Specifying environment indicator is useful for avoiding mistakes
  when testing by having better visibility what environment you are in
  (production/staging/test).

  The following keys need to be specified:

  **background_colour** (string, mandatory)
    Background colour to use for the strip at bottom. This should be value
    compatible with CSS ``background-color`` attribute.

  **text_colour** (string, mandatory)
    Text colour to use for the strip at bottom. This should be value compatible
    with CSS ``color`` attribute.

  **text** (string, mandatory)
    Text to show in show in the strip at bottom.

**fqdn** (string, mandatory)
  Fully-qualified domain name where the website is reachable. This value is used
  for calculating the user/group name for dedicated website user, as well as
  home directory of the website user (where data/code should be stored at).

**index** (string, optional, ``index.php``)
  Space-separated list of files which should be treated as index files by the
  web server. The web server will attempt opening these index files, in
  succession, until the first match, or until it runs out of matches, when a
  client requests an URI pointing to directory.

**http_header_overrides** (dict, optional, ``{}``)
  HTTP headers to set/override on the incoming request before passing
  it on to the PHP application. Keys are HTTP header names, values are
  header values.

  .. note::
     Role takes care of prefixing the headers with ``HTTP_``,
     converting them to upper-case, and replacing dashes with
     underscores - simply pass in the official HTTP header name, no
     extra precautions are required for PHP specifics.

  Double quotes in the value must be escaped with a backslash. Make
  sure to take into account the YAML escaping as well. For example, to
  set the value to ``this is quote - "``, YAML should look like one of
  the following:

  - ``this is double quote - "``
  - ``'this is double quote - \"'``
  - ``"this is double quote - \\\"'``

  To clear a header value, simply set its value to an empty
  string. Nginx variables can be used as well, however keep in mind
  that the dollar sign (``$``) *cannot* be used/escaped due to Nginx
  configuration file syntax limitations.

**https_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``.

**https_tls_key** (string, optional, mandatory)
  Private key used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``.

**php_file_regex** (string, optional, ``\.php$``)
  Regular expression used for determining which file should be interepted via
  PHP.

**php_rewrite_urls** (list, optional, ``[]``)
  A list of rewrite rules that are applied to incoming requests. These rewrite
  rules are specifically targetted at prettying-up the URLs used by the PHP
  scripts. Each element of the list should be a string value compatible with the
  format of ``nginx`` option ``rewrite``. The keyword ``rewrite`` itself should
  be omitted, as well as trailing semi-colon (``;``).

**rewrites** (list, optional, ``[]``)
  A list of rewrite rules that are applied to incoming requests. Each element of
  the list should be a string value compatible with the format of ``nginx``
  option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well
  as trailing semi-colon (``;``).

**packages** (list, optional, ``[]``)
  A list of additional packages to install for this particular PHP
  appliction. This is usually going to be different PHP extensions.

**uid** (integer, optional, ``whatever OS picks``)
  UID/GID (they are set-up to be the same) of the dedicated website
  user/group.

**website_mail_recipients** (string, optional, ``root``)
  Space-separated list of e-mails or local users to which the mails, sent to
  either the website admin or website user, should be forwarded to. Forwarding
  is configured via ``~/.forward`` configuration file.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up two (base) PHP websites (for
running *ownCloud* and *The Bug Genie* applications):

.. code-block:: yaml

    - role: php_website
      fqdn: cloud.example.com
      uid: 2001
      php_file_regex: \.php($|/)
      rewrites:
        - ^/\.well-known/host-meta /public.php?service=host-meta
        - ^/\.well-known/host-meta\.json /public.php?service=host-meta-json
        - ^/\.well-known/carddav /remote.php/carddav/ redirect
        - ^/\.well-known/caldav /remote.php/caldav/ redirect
        - ^/apps/calendar/caldav\.php /remote.php/caldav/
        - ^/apps/contacts/carddav\.php /remote.php/carddav/
        - ^/remote/(.*) /remote.php
      deny_files_regex:
        - ^(\.|autotest|occ|issue|indie|db_|console|build/|tests/|config/|lib/|3rdparty/|templates/).*
      packages:
        # For ownCloud
        - php5-gd
        - php5-json
        - php5-mysql
        - php5-curl
      https_tls_key: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.key') }}"
      https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/cloud.example.com_https.pem') }}"
      additional_nginx_config:
        - comment: Use custom page for forbidden files.
          value: error_page 403 /core/templates/403.php;
        - comment: Use custom page for non-existing locations/files.
          value: error_page 404 /core/templates/404.php;
      additional_fpm_config:
        "env[PATH]": "\"/usr/local/bin:/usr/bin:/bin\""
      website_mail_recipients: "root john.doe@example.com"
      environment_indicator:
        background_colour: "green"
        text_colour: "black"
        text: "TEST ENVIRONMENT"
    - role: php_website
      deny_files_regex:
        - ^\..*
      php_rewrite_urls:
        - ^(.*) /index.php?url=$1
      fqdn: tbg.example.com
      uid: 2007
      https_tls_key: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.key') }}"
      https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/tbg.example.com_https.pem') }}"


WSGI Website
------------

The ``wsgi_website`` role can be used for setting-up a website powered by Python
on destination machine. The website needs to use the WSGI specification for
making the Python web application(s) available.

This role is normally not supposed to be used directly, but should instead serve
as the basis for writing website-specific roles. Therefore the role is written
in quite generic way, allowing the integrator to write his/her own logic for
deploying the necessary Python applications/packages, while still reusing a
common base and reducing the workload.

The role implements the following:

* Creates a dedicated user/group for running the WSGI application.
* Creates a dedicated administrator user for maintaining the website.
* Creates a base directory where the website-specific code and data should be
  stored at.
* Adds nginx to website's group, so nginx could read the necessary files.
* Adds website administrator to website's group, so administrator could manage
  the code and data.
* Installs additional packages required for running the role (as configured).
* Sets-up a dedicated Python virtual environment for website.
* Install Gunicorn in Python virtual environment.
* Installs additional packages required for running the role in Python virtual
  environment (as configured).
* Configures systemd to run the website code (using Gunicorn)
* Deploys the HTTPS TLS private key and certificate (for website vhost).
* Configures nginx to serve the website (static files served directly, requests
  passed on to Gunicorn).

The role is implemented with the following layout/logic in mind:

* No plaintext HTTP is allowed, HTTPS is mandatory. Clients connecting
  via plaintext HTTP are redirected to HTTPS.
* Clients are served with ``Strict-Transport-Security`` header with
  value of ``max-age=31536000; includeSubDomains``. This forces
  compliant clients to always connect using HTTPS to the web server
  when accessing its domain, as well as any subdomains served
  by this web server or any other. The (client-side) cached header
  value expires after one year.
* Website users are named after the ``FQDN`` (fully qualified domain name) of
  website, in format of ``web-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal to
  ``FQDN`` where dots have been replaced by underscores (for example,
  ``web-wiki_example_com``).
* Website users are set-up via GECOS field to have their umask set to ``0007``
  (in combination with ``pam_umask``).
* Administrator users are named after the ``FQDN`` (fully qualified domain name)
  of website, in format of ``admin-ESCAPEDFQDN``, where ``ESCAPEDFQDN`` is equal
  to ``FQDN`` where dots have been replaced by underscores (for example,
  ``admin-cloud_example_com``).
* All websites reside within a dedicated sub-directory in ``/var/www``. The
  sub-directory name is equal to the ``FQDN`` used for accessing the
  website. Owner of the directory is set to be the application administrator,
  while group is set to be the website group. Additionally, ``SGID`` bit is set
  on the directory. This allows admin, with correct umask, to create necessary
  files and directories that should be readable (and eventually writeable) by
  the website user (running the WSGI application) without having to become root.
* All files placed in the website directory should be either created there
  directly, or copied to the directory in order to make sure the ``SGID`` gets
  honored. **Do not move the files, the permissions will not be set correctly.**
* Within the website directory, Python virtual environment can be found within
  the ``virtualenv`` sub-directory. Switching to administrator user via login
  shell will automatically activate the virtual environment.
* Within the website directory, nginx will expect to find the static files
  within the ``htdocs`` sub-directory (this can be symlink too). Locations/aliases
  can be configured for static file serving.
* Within the website directory, systemd service will expect to find the website
  code within the ``code`` sub-directory (this can be symlink too).
* nginx communicates with WSGI server over a dedicated Unix socket for each
  website.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**
* **web_server**


Parameters
~~~~~~~~~~

**additional_nginx_config** (list, optional, ``[]``)
  List providing additional Nginx configuration options to include. This can be
  useful for specifying things like error pages. Options are applied inside of a
  **server** context of Nginx configuration file.

  Each item is a dictionary with the following options describing the extra
  configuration option:

  **comment** (string, mandatory)
    Comment describing the configuration option.

  **value** (string, mandatory)
    Configuration option.

**admin_uid** (integer, optional, ``whatever OS picks``)
  UID of the dedicated website administrator user. The user will be member of
  website group.

**environment_indicator** (dictionary, optional, ``null``)
  Specify configuration for including environment indicator on all
  HTML pages. Indicator is a simple strip at bottom of a page with
  custom background colour, text colour, and text. Indicator can be
  collapsed by clicking on the arrows on the left side of the strip.

  Specifying environment indicator is useful for avoiding mistakes
  when testing by having better visibility what environment you are in
  (production/staging/test).

  The following keys need to be specified:

  **background_colour** (string, mandatory)
    Background colour to use for the strip at bottom. This should be value
    compatible with CSS ``background-color`` attribute.

  **text_colour** (string, mandatory)
    Text colour to use for the strip at bottom. This should be value compatible
    with CSS ``color`` attribute.

  **text** (string, mandatory)
    Text to show in show in the strip at bottom.

**environment_variables** (dict, optional, ``{}``)
  Specify additional environment variables that should be set for running the
  service. Environment variables will be set in both the systemd service and for
  the application's administrator user (when logged in as one).

**fqdn** (string, mandatory)
  Fully-qualified domain name where the website is reachable. This value is used
  for calculating the user/group name for dedicated website user, as well as
  home directory of the website user (where data/code should be stored at).

**https_tls_certificate** (string, mandatory)
  X.509 certificate used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/certs/`` under name ``{{ fqdn }}_https.pem``.

**https_tls_key** (string, mandatory)
  Private key used for TLS for HTTPS service. The file will be stored in
  directory ``/etc/ssl/private/`` under name ``{{ fqdn }}_https.key``.

**packages** (list, optional, ``[]``)
  A list of additional packages to install for this particular WSGI
  website. This is usually going to be development libraries for building Python
  packages.

**http_header_overrides** (dict, optional, ``{}``)
  HTTP headers to set/override on the incoming request before passing
  it on to the WSGI application. Keys are HTTP header names, values are
  header values.

  Double quotes in the value must be escaped with a backslash. Make
  sure to take into account the YAML escaping as well. For example, to
  set the value to ``this is quote - "``, YAML should look like one of
  the following:

  - ``this is double quote - "``
  - ``'this is double quote - \"'``
  - ``"this is double quote - \\\"'``

  To clear a header value, simply set its value to an empty
  string. Nginx variables can be used as well, however keep in mind
  that the dollar sign (``$``) *cannot* be used/escaped due to Nginx
  configuration file syntax limitations.

**rewrites** (list, optional, ``[]``)
  A list of rewrite rules that are applied to incoming requests. Each element of
  the list should be a string value compatible with the format of ``nginx``
  option ``rewrite``. The keyword ``rewrite`` itself should be omitted, as well
  as trailing semi-colon (``;``).

**static_locations** (list, optional, ``[]``)
  List of locations that should be treated as static-only, and not processed by
  the WSGI application at all. This is normally used for designating serving of
  static/media files by Nginx (for example, in case of Django projects for
  ``/static/`` and ``/media/``).

**uid** (integer, optional, ``whatever OS picks``)
  UID/GID (they are set-up to be the same) of the dedicated website
  user/group.

**use_paste** (boolean, optional, ``False``)
  Tell Gunicorn to assume that the passed-in ``wsgi_application`` value is a
  filename of a Python Paste ``ini`` file instead of WSGI application.

**virtuaelnv_packages** (list, optional, ``[]``)
  A list of additional packages to install for this particular WSGI appliction
  in its virtual environment using ``pip``.

**website_mail_recipients** (string, optional, ``root``)
  Space-separated list of e-mails or local users to which the mails, sent to
  either the website admin or website user, should be forwarded to. Forwarding
  is configured via ``~/.forward`` configuration file.

**wsgi_application** (string, mandatory)
  WSGI application that should be started by Gunicorn. The format should be
  conformant to what the ``gunicorn`` command-line tool accepts. If the
  ``use_paste`` option is enabled, the value should be equal to filename of the
  Python Paste ini file, located in the ``code`` sub-directory. It should be
  noted that in either case the value should be specsified relative to the
  ``code`` sub-directory. I.e. don't use full paths.

**wsgi_requirements** (list, optional, ``[ gunicorn==21.2.0, packaging==23.2 ]``)
  Complete list of pip requirements used for deploying Gunicorn. If
  specified, this list will be used to create requirements file and
  install Gunicorn and its dependencies from that one. This allows to
  have pinned packages for both Gunicorn and its dependencies.

  It should be noted that this installation method is meant primarily in case of
  roles that want to take advantage of upgrade checks for pip requirements
  files, and that employ `pip-tools <https://github.com/jazzband/pip-tools>`_.

  In addition to change of installation method, when this parameter is
  specified the role will deploy necessary files for running the pip
  requirements upgrade check (see the ``common`` role for
  description). For this a directory is created under
  ``/etc/pip_check_requirements_upgrades/FQDN``. The same directory
  should be used by dependant roles to deploy their own ``.in`` and
  ``.txt`` files. Make sure the file ownership is set to
  ``root:pipreqcheck``.

  Should you need to utilise the requirements file in some manner (other than
  checking for its upgrades), it will be also stored (and made accessible to
  application user/admin)) in application's home directory under the name
  ``.wsgi_requirements.txt``.

  To create complete requirements list, it is recommended to use `pip-tools
  <https://github.com/jazzband/pip-tools>`_ (the ``pip-compile`` utility) with
  ``gunicorn`` and ``futures`` in the ``.in.`` file.

**wsgi_requirements_in** (list, optional, ``[ gunicorn ]``)
  List of top level packages to use when performing the pip
  requirements upgrade checks for the Gunicorn requirements (listed
  via ``wsgi_requirements`` parameter).


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up a (base) WSGI website (for
running a bare Django project):

.. code-block:: yaml

    # Sample for a Django installation.
    - role: wsgi_website
      fqdn: django.example.com
      static_locations:
        - /static
        - /media
      uid: 2004
      virtualenv_packages:
        - django
      wsgi_application: django_example_com.wsgi:application
      environment_variables:
        DJANGO_SETTINGS_MODULE: "django_example_com.settings.production"
      https_tls_key: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.key') }}"
      https_tls_certificate: "{{ lookup('file', inventory_dir + '/tls/wsgi.example.com_https.pem') }}"
      additional_nginx_config:
        - comment: Use custom page for forbidden files.
          value: error_page 403 /static/403.html;
        - comment: Use custom page for non-existing locations/files.
          value: error_page 404 /static/404.html;
      website_mail_recipients: "root john.doe@example.com"
      environment_indicator:
        background_colour: "green"
        text_colour: "black"
        text: "TEST ENVIRONMENT"
      http_header_overrides:
        Accept-Encoding: ""

    # Use wsgi_requirements to deploy Gunicorn.
    - role: wsgi_website
      fqdn: wsgi.example.com
      wsgi_application: wsgi:main
      wsgi_requirements:
        - gunicorn==19.7.1
	- futures==3.1.1


Database Server
---------------

The ``database_server`` role can be used for setting-up a MariaDB database
server on destination machine.

The role implements the following:

* Installs MariaDB server and client.
* Configures MariaDB server and client to use *UTF-8* encoding by default.
* Sets-up the database root user for passwordless login via UNIX
  socket authentication.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**


Parameters
~~~~~~~~~~

This role has no parameters.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

This role has no parameters which can be configured configure.


Database
--------

The ``database`` role can be used for creating a MariaDB database and
accompanying user on destination machine.

The role implements the following:

* Creates MariaDB database.
* Creates a dedicated user capable of performing any operation on the created
  database. Username is set to be same as the name of database.
* Sets-up pre-backup task that creates database dump in location
  ``/srv/backup/mariadb/{{ db_name }}.sql``.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **database_server**
* **backup_client**


Backups
~~~~~~~

If the backup for this role has been enabled, the following paths are backed-up:

**/srv/backup/maraidb/{{ db_name }}.sql**
  Dump of the database. Database dump is created every day at 01:45 in the
  morning.


Parameters
~~~~~~~~~~

**db_name** (string, mandatory)
  Name of the database that should be created.

**db_password** (string, mandatory)
  Password for the database user.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for creating a single database (for some
website):

.. code-block:: yaml

  - role: database
    db_name: phpinfo_example_com
    db_password: phpinfo_example_com


Backup Server
-------------

The ``backup_server`` role can be used for setting-up a server to act as backup
storage for the backup clients. Storage is made available to the clients
exclusively via SFTP on a dedicated port and dedicated OpenSSH server
instance. This instance is specifically configured and tailored for this
purpose.

The role is primarily aimed for use with `Duplicity
<http://duplicity.nongnu.org/>`_, but should be also usable for generic SFTP
uploads.

The role implements the following:

* Installs backup software (Duplicity, Duply).
* Creates a dedicated directory structure for backups with the following structure:

  * ``/srv/backups/`` - main directory under which all the backups reside.
  * ``/srv/backups/SERVER_NAME/`` - home directory for the backup user, name
    after the server. Backup users are confined to their respective home
    directory via chroot. Backup users can't write to their own home directory,
    though.
  * ``/srv/backups/SERVER_NAME/duplicity/`` - directory where the Duplicity
    backups are stored at. This directory is writable by the respective backup
    user.
  * ``SERVER_NAME/.ssh/`` - directory where authorized keys are stored. Backup
    user is not allowed to make modifications to this directory and files
    contained within (i.e. backup users can't add more keys to the
    ``authorized_keys`` file).
* Creates dedicated operating system users for backup clients. These users will
  be made members of the ``backup`` group as well (as an additional group).
* Sets-up ``authorized_keys`` for the backup clients.
* Makes sure the backup users can't log-in via regular OpenSSH server instance.
* Sets-up dedicated OpenSSH server instances to be used exclusively by backup
  clients. The instance listens on TCP port ``2222``.
* Updates firewall to allow incoming TCP connections to port
  ``2222``. Connections are allowed only from the configured IP addresses
  associated with backup clients.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **common**


Parameters
~~~~~~~~~~

**backup_clients** (list, optional)
  List of backup clients that are connecting to the backup server. This is
  usually done on a per-server basis. Each item in the list is a dictionary
  describing the backup client. The following keys are available:

  **server** (string, mandatory)
    Name of the server that is backed up. It is highly recommended to use
    server's FQDN for this purpose. The dedicated operating system user created
    will have the name of format ``bak-ESCAPED_SERVER_NAME``, where
    ``ESCAPED_SERVER_NAME`` is calculated by taking the passed-in server name
    and replacing all dots (``.``) with undescores (``_``). For example,
    ``web.example.com`` will be turned into ``bak-web_example_com``.

  **uid** (integer, optional, ``whatever OS picks``)
    Uid for the operating system user. User's default group will have a GID
    identical to the user's UID if specified. Otherwise user's default group
    will have OS-determined GID.

  **ip** (IPv4 address, mandatory)
    IPv4 address from which the backup client server is connecting to the backup
    server. Used for introducing stricter firewall rules.

  **public_key** (string, mandatory)
    SSH public key used by backup client to connect to the backup server.

**backup_host_ssh_private_keys** (dictionary, mandatory)
  Defines host keys used for the dedicated OpenSSH server instance for
  backup. Key values that must be provided are:

  - **rsa**
  - **ed25519**
  - **ecdsa**

  Values for each key should be the corresponding private key
  generated using the appropriate algorithm. Keys for this purpose can
  be easily created via commands::

    ssh-keygen -f backup_server_rsa_key -N '' -t rsa
    ssh-keygen -f backup_server_ed25519_key -N '' -t ed25519
    ssh-keygen -f backup_server_ecdsa_key -N '' -t ecdsa


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up the backup server role:

.. code-block:: yaml

  - role: backup_server
    backup_clients:
      - server: web.example.com
        uid: 3000
        public_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com.pub') }}"
        ip: 10.32.64.18
      - server: mail.example.com
        public_key: "{{ lookup('file', inventory_dir + '/ssh/mail.example.com.pub') }}"
        ip: 10.32.64.15
    backup_host_ssh_private_keys:
      rsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key') }}"
      ed25519: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key') }}"
      ecdsa: "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key') }}"


Backup Client
-------------

The ``backup_client`` role can be used for setting-up the server as a backup
client so it can perform backups to the backup server.

Backup clients utilise duplicity (via the duply convenience wrapper) for
performing the backups to a backup server via *SFTP* protocol.

The role itself will take care of deploying the necessary software,
configuration files, and encryption/signing private key to the backup client in
order to be able to perform backup.

Files that should be backed-up are specified using the ``backup`` role.

The role implements the following:

* Installs backup software (Duplicity, Duply).
* Sets-up Duply configuration under directory ``/etc/duply/main/``.
* Deploys encryption/signing private key (usually host-specific), as well as
  additional encryption public keys to the server, and imports them into local
  GnuPG keyring used by backup software.
* Deploys private SSH key for logging-in into the backup server over SFTP.
* Deploys ``known_hosts`` file for SFTP fingerprint verification.
* Sets-up a handler that runs scripts/binaries before the actual backup
  run. This is helpful for producing database backups. Such scripts/binaries
  should be deployed to directory ``/etc/duply/main/pre.d/``, and marked
  executable by the root user.

Duply is configured as follows:

* GnuPG keyring is stored under ``/etc/duply/main/gnupg/``. The keyring should
  not be managed manually.
* SSH private key for logging-in into backup server is stored in location
  ``/etc/duply/main/ssh/identity``. Backup server SFTP fingerprint is stored in
  location ``/etc/duply/main/ssh/known_hosts``.
* Base directory for back-ups is root (``/``), but *all* files are excluded by
  default to prevent huge back-ups. Ansible roles that want to utilise the
  backup client role can specify which patterns should be included in the backup
  when including the ``backup`` role. Include pattern file is assembled and
  stored in location ``/etc/duply/main/include``.
* Backups are encrypted and signed with the specified encryption key.
* Maximum age for old backups is set to 6 months.
* Maximum age for full backups is set to 1 month.
* Volume size is set to 1GB.
* Pre-backup scripts are run via ``/etc/duply/main/pre`` handler that tries to
  execute scripts/binaries from directory ``/etc/duply/main/pre.d/``.
* Pre-backup scripts must run successfully for the actual backup
  process to proceed.
* Old backups are automatically purged in case of successful run.

.. note::
   Since at time of this writing there are no lookup plugins for extracting key
   material/information from GnuPG keyring, you may want to resort to extraction
   of keys on the controller machine via lookups similar to::

     lookup('pipe', 'gpg2 --homedir /path/to/your/keyring --armor --export some_identifier')
     lookup('pipe', 'gpg2 --homedir /path/to/your/keyring --armor --export-secret-keys some_identifier')

   This may not be the most elegant solution, but for now it offers better
   flexibility (theoretically, you could store all those keys etc as plaintext
   files instead).


Parameters
~~~~~~~~~~

**backup_additional_encryption_keys** (list, optional, ``[]``)
  List of additional public encryption keys used for backup operation. Each item
  in the list should be an ASCII armour-encoded public key exported from a GnuPG
  keyring. These additional public keys are useful in cases where the backups
  should be decryptable with some master key in addition to server-specific key.

**backup_client_username** (string, optional, ``bak-{{ ansible_fqdn | replace('.', '_') }}``)
  Username for connecting to the backup server via SFTP.

**backup_encryption_key** (string, mandatory)
  Private GnuPG key, encoded using ASCII armor, used for encryption and signing
  operations when running the backup on the client server. This *must* be a
  private key! This is normally host-specific encryption key that is distributed
  to destination server and that can be also used for the restore operations
  (for data decryption). The key must not be password-protected.

**backup_server** (string, mandatory)
  Backup server to connect to.

**backup_server_destination** (string, optional, ``/duplicity``)
  Target directory on the backup server where the backups are stored.

**backup_server_host_ssh_public_keys** (list, mandatory)
  SSH public keys presented by the server during client authentication. These
  public keys are used for populating the known hosts on the backup client side
  for host verification purposes.

**backup_server_port** (int, optional, ``2222``)
  Port on the backup server to connect to for accessing the SFTP service.

**backup_ssh_key** (string, mandatory)
  SSH private key for logging-in into the backup server.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up the role (take note that lookup
plugin is quite useful here for fetching key values from some local directory):

.. code-block:: yaml

  - role: backup_client
    backup_additional_encryption_keys: "-----BEGIN PGP PUBLIC KEY BLOCK-----\n...\n-----END PGP PUBLIC KEY BLOCK-----"
    backup_client_username: "user"
    backup_encryption_key: "-----BEGIN PGP PRIVATE KEY BLOCK-----\n...\n-----END PGP PRIVATE KEY BLOCK-----"
    backup_server: "backup.example.com"
    backup_server_destination: "//example/host"
    backup_server_host_ssh_public_keys:
      - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ecdsa_key.pub') }}"
      - "{{ lookup('file', inventory_dir + '/ssh/backup_server_ed25519_key.pub') }}"
      - "{{ lookup('file', inventory_dir + '/ssh/backup_server_rsa_key.pub') }}"
    backup_server_port: 22
    backup_ssh_key: "{{ lookup('file', inventory_dir + '/ssh/web.example.com') }}"


Backup
------

The ``backup`` role can be used to specify what files should be backed-up to the
backup server.

The role provides a convenient way to deploy a file containing file and
directory patterns describing the file/directory paths that should be included
in the back-up.

The role implements the following:

* Installs a file with provided patterns in directory
  ``/etc/duply/main/patterns/``.
* Assembles/refresshes the main include pattern file at
  ``/etc/duply/main/include``.


Role dependencies
~~~~~~~~~~~~~~~~~

Depends on the following roles:

* **backup_client**


Parameters
~~~~~~~~~~

**backup_patterns_filename** (string, mandatory)
  Name of the backup patterns file. The file is stored in directory
  ``/etc/duply/main/patterns/``. This should be a unique filename amongst all
  roles. If role can be included multiple times, make sure the filename is
  always unique when depending on the backup role.

**backup_patterns** (list, optional, ``[]``)
  List of globbing patterns defining which files or directories should be
  backed-up.


Distribution compatibility
~~~~~~~~~~~~~~~~~~~~~~~~~~

Role is compatible with the following distributions:

- Debian 12 (Bookworm)


Examples
~~~~~~~~

Here is an example configuration for setting-up the role:

.. code-block:: yaml

  - role: backup
    backup_patterns_filename: myapp
    backup_patters:
      - /var/www/myapp.example.com