NethServer Documentation · 2019. 4. 2. · 49 CUPS 145 49.1 Conﬁguration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 49.2 Printer

NethServer DocumentationRelease 7

Nethesis

February 09, 2017

Rules and conventions

1 Introduction 31.1 Target audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Get involved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 Development process 52.1 Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 RPM Version numbering rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.3 Commit message style guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.5 New packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3 RPM package rules 93.1 Naming and events conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.2 Install/Update process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Uninstall process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.4 Service packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4 Internationalization 134.1 gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134.2 Server Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

5 Databases 155.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.2 Simple entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.3 Complex entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.4 Access from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155.5 Access via the Perl API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.6 Database initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165.7 Evaluation order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.8 Best practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185.9 List of available database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

6 Templates 216.1 Design of the template system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.2 The Text::Template module . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216.3 Template expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256.4 Template permissions and ownership: templates.metadata . . . . . . . . . . . . . . . . . . . . . . . 256.5 Perl API: processTemplate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

i

7 Actions and events 277.1 Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

8 Services 338.1 Control a service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.2 Access network service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338.3 Add a new service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348.4 Add a new network service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

9 Filesystems options 37

10 DNS 3910.1 Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3910.2 DNS server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

11 DHCP 4111.1 IP reservation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

12 Log retention and rotation 43

13 Auto-generated random URL 45

14 Migration from NethService/SME Server 4714.1 Coding conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4714.2 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

15 Certificate Management 5115.1 Default behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

16 Yum plugin 5316.1 Caching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

17 Backup 5517.1 Log format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5517.2 Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5617.3 Configuration backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5617.4 Data backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

18 Samba 6118.1 Ibay profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6118.2 Accounts database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6218.3 Active Directory domain member . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6318.4 Changing hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

19 Web interface 6719.1 Nethgui framework . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

20 Creating web UI module 6920.1 Web UI structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6920.2 Writing the code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7020.3 More examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

21 Dashboard 7321.1 SystemStatus tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7321.2 Services tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

ii

21.3 Applications tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7421.4 Extending the dashboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

22 Creating inline help pages 7722.1 Editing rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7722.2 Creating help for plugin modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7822.3 Building docs inside RPMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7822.4 RST editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

23 TODO API 8123.1 Translations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

24 Building RPMs 8324.1 Configuring the environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8324.2 Running the scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8324.3 Development and Release builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8424.4 Signing RPMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8424.5 Creating a release tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

25 Building ISO 87

26 Repositories 8926.1 Third party repositories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

27 Package groups 9127.1 Generate comps file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

28 FTP 9328.1 Virtual users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9328.2 System users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

29 UPS 9529.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9529.2 Master node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9529.3 Slave node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9529.4 Collectd-nut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

30 TFTP 9730.1 Properties: . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9730.2 Test TFTP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9730.3 Configure a PXE server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

31 Webmail (Roundcube) 10131.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

32 Collectd 10332.1 Ping plugin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10332.2 Web interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10432.3 Cleanup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10432.4 Interesting plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10432.5 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

33 Phone Home 10533.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10533.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

iii

34 Web antivirus 10734.1 Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10734.2 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10734.3 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

35 Web content filter 10935.1 Blacklists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10935.2 Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10935.3 Block page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11235.4 Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

36 WebVirtMgr 11336.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

37 Disk analyzer (Duc) 11537.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

38 SNMP 11738.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117

39 Tomcat 7 119

40 PostgreSQL 12140.1 Access policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12140.2 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

41 UnixODBC 12341.1 /etc/odbc.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12341.2 /etc/odbcinst.ini . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12341.3 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

42 VPN 12542.1 Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12542.2 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12642.3 Accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12642.4 Clients (OpenVPN) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12742.5 OpenVPN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12842.6 IPsec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

43 Unbound 13343.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

44 Ntopng 13544.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.2 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.3 Database Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.4 Configuration DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13544.5 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

45 Samba-audit 137

46 Redis 139

47 Memcached 141

48 SMARTD 143

iv

49 CUPS 14549.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14549.2 Printer discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14549.3 Old Windows clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14549.4 Configuration DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

50 Clamd 147

51 c-icap 14951.1 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

52 IAX modem 15152.1 Multiple IAX modems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151

53 MySQL 15353.1 Loading data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

54 nethserver-avahi 155

55 nethserver-base 15755.1 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15755.2 Password policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

56 nethserver-dc 16356.1 nethserver-dc-save event . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16356.2 Manual Join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16356.3 Factory reset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16456.4 Changing the IP address of DC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

57 nethserver-directory 16757.1 Schema and base DN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16757.2 User account states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16857.3 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16857.4 Service accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16857.5 User accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16957.6 Anonymous access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16957.7 Administrative access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16957.8 Inspect OpenLDAP ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

58 nethserver-ejabberd 17158.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

59 nethserver-firewall-base 17359.1 Roles and zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17359.2 General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17459.3 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17559.4 Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17559.5 IP/MAC binding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17559.6 Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17559.7 Firewall objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17759.8 Port forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17959.9 NAT 1:1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17959.10 Traffic shaping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18059.11 Multi WAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18159.12 Static routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

v

60 nethserver-getmail 18560.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18560.2 Virus check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

61 nethserver-httpd 18761.1 Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18761.2 Web applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18761.3 Configuration database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18861.4 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

62 nethserver-httpd-admin 18962.1 smwingsd daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18962.2 Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19062.3 Database example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

63 nethserver-hylafax 19363.1 Modem configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19363.2 Accounting (FaxAccounting) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19363.3 Incoming fax (FaxDispatch) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19363.4 Outgoing fax (FaxNotify) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19463.5 Custom scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19463.6 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19463.7 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19463.8 Client configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19463.9 Configuration DB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

64 nethserver-lightsquid 19764.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

65 nethserver-mail-common 19965.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19965.2 Configuration database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19965.3 Testing Postfix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

66 nethserver-mail-filter 20166.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20166.2 Configuration database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20166.3 RBL server list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

67 nethserver-mail-server 20367.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20367.2 Configuration database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20367.3 Domains database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20467.4 Accounts database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20567.5 Mail quota . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20567.6 Disabled users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20667.7 Testing Dovecot with Mutt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20667.8 Set special ACL on mailboxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

68 nethserver-nextcloud 20768.1 Admin user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20768.2 Backup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

69 nethserver-ntp 20969.1 How it works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

vi

70 nethserver-squid 21170.1 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21170.2 Transparent mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21270.3 Authenticated mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21270.4 Bypasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21370.5 Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21370.6 WPAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21370.7 Miscellaneous options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

71 nethserver-sssd 21571.1 Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21571.2 System users and groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21771.3 NethServer::SSSD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21871.4 Join Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21871.5 Leave and Re-Join Active Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21871.6 Change the FQDN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21971.7 Account import scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220

72 nethserver-suricata 22172.1 Manually enable/disable Suricata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22172.2 Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22172.3 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

73 nethserver-virtualhosts 22373.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22373.2 UI plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

74 nethserver-webtop4 22574.1 Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22574.2 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22574.3 Known problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

75 License Headers 22775.1 PHP, Javascript, CSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22775.2 Perl, Python and BASH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

76 Rebranding Administrator Manual 22976.1 Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22976.2 Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22976.3 Product name and version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23076.4 Theme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23076.5 Artworks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

77 License 231

78 Indices and tables 233

vii

NethServer Documentation, Release 7

Official site: http://www.nethserver.org

Rules and conventions 1

http://www.nethserver.org


2 Rules and conventions

CHAPTER 1

Introduction

NethServer is an Open Source operating system for the Linux enthusiast, designed for small offices and mediumenterprises. It’s simple, secure and flexible.

NethServer is ready to deliver your messages, to protect your network with the built-in firewall, share your files andmuch more, everything on the same system.

1.1 Target audience

This manual is intended for developers who are interested about NethServer internals. Reading this manual you shouldbe able to learn how to extend, enpower and debug the NethServer platform.

1.2 Get involved

The NethServer project welcomes anyone who would like to become involved in the project. This is a brief list ofthings to do (in a sparse order):

• Writing documentation

• Bug reporting, bug triaging, QA testing

• Translating the web interface

• Developing / coding in Perl, PHP, Python, Bash

Note: This manual is a work in progress. If you can’t find some information please check also our wiki:http://wiki.nethserver.org and always feel free to ask on http://community.nethserver.org

3

http://wiki.nethserver.orghttp://community.nethserver.org


4 Chapter 1. Introduction

CHAPTER 2

Development process

2.1 Issues

An issue is a formal description of a known problem, or wished feature, inside a tracker. There are two types of issues:

Bug describes a defect of the software; it must lead to a resolution of the problem. For example, a process crashingunder certain conditions.

Enhancement describe an improvement of the current code or an entire new feature. For example, remove harmlesswarning of a running process or designing a new UI panel.

Bugs and enhancements will always produce some code changes inside a one or more git repositories.

Each repository is associated to one or more RPM packages. Changes to the code produce new releases of RPMpackages.

2.1.1 Do I need to open a new issue?

Yes, if what you’re talking about will produce some code. By the way, it’s perfectly reasonable to not fill issues foroccasional small fixes, like typos in translations.

Issues are not a TODO list. Issues track the status changes of a job, the output of the job will be a new RPMimplementing the issue itself. If you are exploring some esoteric paths for new feature or hunting something like anheisenbug , please write a draft wiki page with your thoughts, then create a new issue only when you’re ready to writea formal description and produce some output object.

A process for a new feature, can be something like this:

• Open a new topic on http://community.nethserver.org and discuss it.

• Open the issue on GitHub https://github.com/NethServer/dev/issues/new.

If the feature is very complex, a dedicated wiki page could be written on http://wiki.nethserver.org/.

• Create a wiki page with notes and thoughts (team contributions are welcome!).

• When the wiki page is pretty “stable” and the whole thing is well outlined, a team member will create one ormore new issues.

• If the wiki page is a feature design document, the feature can simply point to the wiki page.

• The wiki page should become a technical documentation of the feature, or a changelog for a new release.

At any point in time, make sure the issue status reflects actual work.

5

http://en.wikipedia.org/wiki/Heisenbughttp://community.nethserver.orghttps://github.com/NethServer/dev/issues/newhttp://wiki.nethserver.org/


2.1.2 Writing issues

How to write a bug report:

• Apply the bug label

• Point to the right software component with the associated version

• Describe the error, and how to reproduce it

• Describe the expected behavior

• If possible, suggest a fix or workaround

• If possible, add a piece of system output (log, command, etc)

• Text presentation matters: it makes the whole report more readable and understandable

How to write a feature or enhancement:

• Everybody should understand what you’re talking about: describe the feature with simple words using examples

• If possible, add links to external documentation

• Text presentation matters: it makes the whole report more readable and understandable

More information:

• https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelines

• http://fedoraproject.org/wiki/Bugs_and_feature_requests

• http://fedoraproject.org/wiki/How_to_file_a_bug_report

2.1.3 Issue tracker

The NethServer project is hosted on GitHub and is constituted by many git repositories. We set one of them to be theissue tracker:

https://github.com/NethServer/dev

Issues created on dev help coordinating the development process, determining who is in charge of what.

Developer

The Developer.

• Sets the Assignee to himself.

• Bundle his commits as one or more GitHub pull requests, reporting the issue number reference on them (seealso Commit message style guide).

• For enhancements, writes the test case (for bugs the procedure to reproduce the problem should be already set).

• Writes and updates the Documentation associated with the code.

• Finally, clears the Assignee.

If the issue is not valid, he can close it adding one of the labels invalid, duplicate, wontfix.

6 Chapter 2. Development process

https://developer.mozilla.org/en-US/docs/Mozilla/QA/Bug_writing_guidelineshttp://fedoraproject.org/wiki/Bugs_and_feature_requestshttp://fedoraproject.org/wiki/How_to_file_a_bug_reporthttps://github.com/NethServer/dev


QA team member (testing)

The QA team member.

• Takes an unassigned issue with label testing and sets the Assignee field to herself.

• Tests the package, following the test case documentation written by the Developer.

• When test finishes she removes the testing label and clears Assignee field. If the test is successful, she sets theverified label, otherwise she alerts the Developer and the Packager to plan a new process iteration.

Packager

The Packager coordinates the Developer and QA member work. After the Developer opens one or more pull requests:

• Selects issues with open pull requests

• Reviews the pull request code and merges it

• Builds and uploads the RPMs to the testing repository and sets the testing label (see Building RPMs)

After the QA member has completed the testing phase:

• Takes an unassigned issue with label verified

• Commits a release tag (see ‘Building RPMs‘_).

• Re-builds the tagged RPM.

• Uploads the RPM to updates (or base) repository.

• Pushes the release tag and commit to SCM

• Closes the issue, specifying the list of released RPMs

When the package is CLOSED, all related documentation must be in place.

2.2 RPM Version numbering rules

NethServer releases bring the version number of the underlying CentOS. For example NethServer 7 beta1 isbased on CentOS 7.

Packages have a version number in the form X.Y.Z-N (Eg. nethserver-myservice-1.0.3-1.ns7.rpm):

• X: major release, breaks retro-compatibility

• Y: minor release, new features - big enhancements

• Z: bug fixes - small enhancements

• N: spec modifications inside the current release - hotfixes

2.3 Commit message style guide

Individual commits should contain a cohesive set of changes to the code. These seven rules summarize how should begood commit message.

1. Separate subject from body with a blank line

2. Limit the subject line to 50 characters

2.2. RPM Version numbering rules 7

http://chris.beams.io/posts/git-commit/#seven-rules


3. Capitalize the subject line

4. Do not end the subject line with a period

5. Use the imperative mood in the subject line

6. Wrap the body at 72 characters

7. Use the body to explain what and why vs. how

2.4 Documentation

The developer must take care to write all documentation on:

• wiki page during development

• Developer Manual and/or README.rst before release

• Administrator Manual before release

• Inline help before release

Packages should be inside testing or nethforge-testing repositories until all documentation is completed.

2.5 New packages

Before creating a new package, make sure it’s a good idea. Often a simple documentation page is enough, and itrequires much less effort. When trying new things, just take care to write down on a public temporary document(maybe a wiki page) all steps and comments. If the feature collects many requests, it’s time to think about a newpackage. Otherwise, the temporary document can be moved to a manual page.

When creating a new package, make sure the following requirements are met:

• Announce it on http://community.nethserver.org

• Create an issue describing the package

• Create a personal repository on GitHub

• Add a GPL license and copyright notice in the COPYING file

• Add a README.rst file, with developer documentation

• If needed, create a pull request for the NethServer/comps or NethServer/nethforge-comps repository, to list thepackage in the Software center page.

• Build the package and push it to testing or nethforge-testing repository

See also Building RPMs.

8 Chapter 2. Development process

http://community.nethserver.org

CHAPTER 3

RPM package rules

3.1 Naming and events conventions

Each package name MUST be composed of

• a prefix, corresponding to the product name: nethserver-, neth-, ....

• the feature/function/daemon/software: base, directory, httpd-admin ...

Each package MUST contain:

• -update event, raised each time the package is installed/updated and when the sys-tem is re-configured (for instance, after another package has been uninstalled)

The update event should:

• configure the package on first install

• take care of upgrading current installation in case of package update

Note: You should not add code in %post and %pre sections of the spec file. All the logic must be inside the -updateevent.

Each package MAY contain:

• -save event, raised by the console or the web interface to adjust the package configurationafter some DB value has changed;

• -conf action, to execute package-specific configuration commands. This action MUST beinvoked during the -update event.

For example, given a package named nethserver-dnsmasq:

• update event: nethserver-dnmasq-update

• save event: nethserver-dnmasq-save

• configuration action: nethserver-dnmasq-conf

3.2 Install/Update process

Just after a package transaction (install/update), the NethServer yum plugin will:

• execute all nethserver-update-: events of installed/updated packages in the current transaction

9


• execute runlevel-adjust event to start/stop all configured services

• execute firewall-adjust event to open/close firewall ports

In case of manual installation , the update, firewall-adjust and runlevel-adjust events must be fired manually using thesignal-event command.

3.3 Uninstall process

After a package is removed, the NethServer yum plugin will:

• execute all nethserver-update-package event of installed packages

• execute runlevel-adjust event to start/stop all configured services

• execute firewall-adjust event to open/close firewall ports

3.4 Service packages

A service package is an RPM which is responsible for a system service configuration and management. The packagemust follow all rules listed above plus some more conventions.

3.4.1 Configuration DB default

Mandatory:

• type: service

• status: the current service status, can be enabled or disabled

Optional:

• TCPPort: a tcp listening port

• UDPPort: a udp listening port

• TCPPorts: a list of tcp listen ports. Eg: 123,678

• UDPPorts: a list of udp listen ports. Eg: 123,678

For example, the package nethserver-puppet managing the service puppet will contain:

• /etc/e-smith/db/configuration/defaults/puppet/type

• /etc/e-smith/db/configuration/defaults/puppet/status

Beside this, each packge MUST always declare its own set of keys and properties inside default databases.

3.4.2 Events and actions

nethserver-base package provides two generic events:

• runlevel-adjust: enable/disable the service using chkconfig command and start/stop the service

• firewall-adjust: read TCPPort(s) and UDPPort(s) props and open the specified ports in the firewallconfiguration

10 Chapter 3. RPM package rules


Both events are handled by the system, so there is no need to link these events into the package.

Further documentation: perldoc /usr/share/perl5/vendor_perl/NethServer/Service.pm

3.4.3 Orphan services

During runlevel-adjust event, the system will stop any orphan service. A orphan service is a running service notcontrolled by any nethserver-package. A service is an orphan if there is a service record in configuration db, and thereis no db defaults (in /etc/e-smith/db/configuration/defaults).

3.4. Service packages 11


12 Chapter 3. RPM package rules

CHAPTER 4

Internationalization

These are the coding conventions for NethServer i18n. Each package repository should respect them.

• The developer prepares the translation source strings when he writes the code.

• Each translation catalog must be mapped to a resource on Transifex.

• Whenever new strings are added or existing ones are changed, source catalogs must be pushed into Transifexwith Transifex client:

tx push -s

To configure the Transifex client execute the txinit.sh script on the repository root. The script can be executed multipletimes, if new catalogs are added to the repository.

Currently both gettext and Server Manager specific format is supported for language catalogs.

4.1 gettext

The xgettext command can be used to extract strings from the source code. The resulting .pot file must be namedlocale/.pot.

4.1.1 gettext example

In this example we will translate a new TODO message for the web interface.

Steps to setup translation for a new todo:

1. Be sure gettext is installed in your system

2. Add the todo script to the git repository

3. Create locale directory inside the git repository root:

mkdir locale/

4. Extract the strings (from a Python source code):

PACKAGE=$(basename `pwd`)xgettext --msgid-bugs-address "[email protected]" --package-version "1.0.0" \--package-name "$PACKAGE" --foreign-user -d "$PACKAGE" -o "locale/${PACKAGE}.pot" \-L Python root/etc/nethserver/todos.d/*

5. Run the txinit.sh script and commit newly created files into git.

13

https://www.transifex.com/projects/p/nethserverhttp://docs.transifex.com/developer/client/https://gist.github.com/DavidePrincipi/8e4d4e97831d0850f01a


6. Upload the new .pot resource to Transifex (special permissions are needed):

tx push -s

4.2 Server Manager

All source language catalog files are placed in root/usr/share/nethesis/NethServer/Language/en.We assume en is en-US.

The catalog format is a common PHP file where the array variable $L is assigned some keys:

.

2. Use UTF-8 encoding.

Given a module with name “Test”, the source language file will be root/usr/share/nethesis/NethServer/Language/en/NethServer_Module_Test.php.

When the Server Manager is running in debug mode, missing translation labels can be found in/var/log/messages. To enable the debug,

• Unlock index_dev.php controller:

touch /usr/share/nethesis/nethserver-manager/debug

• Prepend index_dev.php on URLs path, eg: https:///index_dev.php/en/.

14 Chapter 4. Internationalization

CHAPTER 5

Databases

5.1 Overview

All user-editable configuration parameters on NethServer are stored in plain text database.

These values are used to generate the system configuration files, such as those found in the /etc/ directory. Theconfiguration databases may be modified by various programs on the system, including the web interface or scriptsrun from the command line by a system administrator.

Each entry in the database is either a simple key/value pair or a key and a collection of related property/value pairs.

5.2 Simple entries

Simple configuration database entries take the form of a key/value pair:

[root@nsrv -]# config show SystemNameSystemName=myserver

5.3 Complex entries

More complex entries consist of a key, a type, and a collection of property/value pairs:

[root@nsrv -]# config show sysconfigsysconfig=configuration

Copyright=ProductName=NethServerRegistration=noneRelease=4Version=6.4

Use complex entries whenever possible

5.4 Access from the command line

You can access database entries from the command line using the config command, as shown above, or the dbcommand. The config command provides a shorthand for accessing the configuration database. The followingcommands are equivalent:

15


[root@nsrv -]# config show SystemNameSystemName=nsrv

[root@nsrv -]# db configuration show SystemNameSystemName=nsrv

The db command allows you to access all of the databases. For example to show the details of the test entry fromaccounts db:

[root@nsrv -]# db accounts show testtest=user

City=Company=Department=FirstName=testLastName=testPhoneNumber=Street=Uid=5000VPNClientAccess=yesVPNRemoteNetmask=255.255.255.0VPNRemoteNetwork=192.168.1.0

For more options see help of db command:

db -h

5.5 Access via the Perl API

You can also access configuration database entries programmatically using the esmith::ConfigDB and relatedPerl modules, which are abstractions for the esmith::DB module. For example, we can retrieve and show theadmin account details like this:

use esmith::AccountsDB;my $db = esmith::AccountsDB->open or die "Couldn't open AccountsDB\n";my $admin = $db->get("admin") or die "admin account missing from AccountsDB\n";print $admin->show();

For documentation on Perl API use the perldoc command. Eg:

perldoc esmith::ConfigDB

5.6 Database initialization

The configuration databases are initialized from files in the /etc/e-smith/db/ hierarchy. These files can performone of three actions:

• Create a database entry and set it to a default value, if the entry does not already exist.

• Migrate an entry from a previous value to a new value.

• Force a database entry to a specific value, regardless of its current setting (use with care!)

This design allows each package to provide part of the system configuration, or migrate the system configurationvalues as required. Note that a single database property can only be owned by one package. Database initialization isrun during system install, system upgrade and after new software has been installed.

16 Chapter 5. Databases


If you examine the /etc/e-smith/db/configuration/ directory you will see three subdirectories:defaults/, force/ and migrate/ to match the three options above. A similar structure exists for each of theother databases. A new database can be created by populating a new directory tree under the /etc/e-smith/db/directory.

Configuration databases can also be initialized using a special /usr/libexec/nethserver/initialize--databasescript, where dbname is the database name. For example: /usr/libexec/nethserver/initialize-mycustomdb-database.

5.6.1 Defaults files

Defaults files are simple text files. If the corresponding database key/property already exists, it is skipped. Otherwise,the key/property is created and the value loaded. For example, this file:

[root@nsrv -]# cat /etc/e-smith/db/configuration/defaults/sshd/statusenabled

It would create the sshd database entry if it doesn’t already exist, create the status property for that entry, again ifit doesn’t already exist, and finally set the status property to enabled.

Forcing database initialization

Simply call the action: /etc/e-smith/events/actions/initialize-default-databases

5.6.2 Force files

Force files are just like defaults files, except they overwrite the existing value. So, this file:

[root@nsrv -]# cat /etc/e-smith/db/configuration/force/sysconfig/Version6

It would create the Version property of the sysconfig entry and unconditionally set its value to 6.

Warning: Do not use force fragments if not really necessary!

5.6.3 Migrate fragments

Migrate fragments are small pieces of Perl text which can be used to perform more complex migrations than is possiblewith defaults and force files. They would normally be used to replace database keys or properties with new names, orto adjust policy settings during an upgrade.

Each fragment is passed a reference to the current database in the $DB variable. This variable is an in-stance of the appropriate esmith::DB subclass, e.g. esmith::AccountsDB when the accounts database mi-grate fragments are being executed. This means that you can use the methods of that subclass, for exampleesmith::AccountsDB->users().

Here is an example of a migrate fragment, which replaces the outdated popd entry with the new name pop3:

{my $popd = $DB->get("popd") or return;my $pop3 = $DB->get("pop3") || $DB->new_record("pop3", { type => "service" });$pop3->merge_props($popd->props);$popd->delete;

}

5.6. Database initialization 17


This fragment checks whether the database (the configuration database in this case) has a popd entry. If that entrydoes not exist, the migrate fragment returns immediately. If the popd entry exists, we need to convert it, so we retrievethe pop3 entry (or create it if it doesn’t already exist). We then merge the properties from the popd entry into thepop3 entry and finally delete the popd entry.

If this migrate fragment is run again, it will return immediately as the popd entry has already been deleted.

Important notes about migrate fragments

• Please be careful with migrate fragments. Although they should only modify entries within the current database,there are no restrictions placed on what they can do. The ability to open and even modify other databases maybe required to perform a migration.

• Migrate fragments must be safe to run multiple times. They should migrate the value when required and donothing in other cases.

• Migrate fragments should never call croak or die. This will cause the database migration to stop. If an erroris detected, call carp or warn to note the error in the logs.

• Migrate fragments should call good termination with return(0) rather than exit(0).

• Migrate fragments should be owned by the package requiring the migration so that the migration only occurswhen that package is installed.

• Migrate fragments should be self-contained and ideally perform only one migration per fragment.

• DO NOT USE to initialize default database values.

5.7 Evaluation order

When a database is loaded:

• migrate scripts are run first

• then defaults are loaded

• and finally any force files are loaded.

This order allows migration of old format entries to occur prior to loading of new default values. Remember, defaultswill not change an existing database property.

5.8 Best practices

• The configuration databases should only be modified using the tools and APIs provided.

• The order of the entries and the order of properties is undefined.

• The keys and property names are currently treated in a case-sensitive manner, though this may change in thefuture. Do not create keys or property names which differ only by their case.

• Underscores and hyphens are valid in key and property names, but should normally be avoided.

• Do not “overload” an existing property with a new value. If the existing values do not meet your requirements,discuss your implementation with the developers. Values which are not known by the base may cause seriousissues on upgrade. If the existing panels have three choices, do not invent new choices without enhancing thepanel to support them.

• The type pseudo-property is used internally and is reserved .



• By convention, database keys are lower case, and property names are stored in mixed case. The type, statusand access properties are exceptions to this convention.

• The storage location and internals of the databases is subject to change.

• The configuration databases are currently stored as pipe-delimited flat text files in the/var/lib/nethserver/db/ directory.

5.8.1 Namespace issues

All entries in a single database share the same namespace. Users, groups, information bays, printers, and other entriesin the accounts database currently all share one namespace. This means that you cannot have a user with the samename as an information bay, group or other entry in the accounts database.

However, it would be possible to have a host named fredfrog as well as a user named fredfrog as they are stored inseparate databases and thus different namespaces.

5.9 List of available database

5.9.1 Table of databases

The following table summarizes

• the database name

• the perl module that manages it and

• the package that provides it

Databases provides by the base system:

Name Perl module Package Descriptionconfiguration esmith::ConfigDB nethserver-basehosts esmith::HostsDB nethserver-hostsnetworks esmith::NetworksDB nethserver-basedomains esmith::DomainsDB nethserver-mail-common

Each modules can define its own new databases. Some relevant databases are:

Name Perl module Package Descriptionaccounts esmith::AccountsDB nethserver-directorydomains esmith::DomainsDB nethserver-mail-common

5.9. List of available database 19

CHAPTER 6

Templates

6.1 Design of the template system

Every piece of software has its own configuration format, and writing parsers for each one is a complex, time-consuming and error-prone process. The template system software avoids the whole issue by using templates whichgenerate the correct configuration.

Configuration files are over-written when templates are expanded. In a few specific cases, the existing configurationfile is parsed and rewritten in-place. This is done where the configuration file (e.g. /etc/fstab) is also automati-cally updated by some other process.

Templates are stored under /etc/e-smith/templates/ in a directory hierarchy whichmatches the standard filesystem. For example, the template for /etc/inittab is stored in the/etc/e-smith/templates/etc/inittab/ directory. Each template is stored as a directory of tem-plate fragments and processed by the Perl Text::Template module.

The template fragments are concatenated together in ASCIIbetical order (US-ASCII sort order) and the complete fileis parsed to generate the appropriate configuration files for the service. The use of fragments is part of NethServermodular and extensible architecture; it allows third-party modules to add fragments to the configuration where neces-sary.

6.2 The Text::Template module

The Text::Template module allows arbitary Perl code to be embedded in a template file by surrounding it incurly braces ({ and }). The code inside the braces is interpreted and its return value replaces the section between, andincluding, the braces. For instance:

The answer is { 40 + 2 }

becomes:

The answer is 42

Variables can be passed in from the program which is expanding the template, hence:

{$OUT = ';'for my $item ( qw(bread milk bananas) ){

$OUT .= "\* $item\n";

21


}}

would expand to:

Shopping list

* bread

* milk

* bananas

The template system uses this mechanism to automatically pass in global configuration variables from the configura-tion database which can then be used to fill out the configuration files.

For example, the /etc/hosts template could be fairly simple and composed of two fragments:

[root@test hosts]$ ls /etc/e-smith/templates/etc/hosts10localhost 20hostname

Fragments can have static content. For example:

127.0.0.1 localhost

The second is more complex and relies on values from the configuration database:

{$OUT .= "$LocalIP\t";$OUT .= " ${SystemName}.${DomainName}";$OUT .= " ${SystemName}";

}

Note that the whole fragment is enclosed in braces. Within those braces is a section of Perl code.

When this template is expanded, it results in the following configuration file:

# ================= DO NOT MODIFY THIS FILE =================## Manual changes will be lost when this file is regenerated.## Please read the developer's guide, which is available# at https://dev.nethesis.it/projects/nethserver/wiki/NethServer# original work from http://www.contribs.org/development/## Copyright (C) 2015 Nethesis S.r.l.# http://www.nethesis.it - [email protected]#127.0.0.1 localhost192.168.10.1 nsrv.nethesis.it nsrv

The header block comes “for free” as part of the template system, courtesy of an optional file template-begin,which is always processed as the first fragment. If it isn’t provided, the text shown with # comments is in-cluded. If target configuration file do not support line comment beginning with #, please provide a custom or emptytemplate-begin.

The other lines are provided by the two fragments shown above. Note the use of the configuration database variables:$LocalIP, $SystemName and $DomainName. All simple entries in the configuration database are provided asglobal variables to the templates.

Note that all of the template fragments are concatenated together before evaluation, so it is possible to set values infragments which are used in later fragments. This is a very useful model for reducing the code in individual templatefragments.

22 Chapter 6. Templates


The complex entries in the configuration database are also provided as global variables to the templates. However,they are provided as Perl hashes instead of simple scalars. For example, here is how you might configure the NetworkTime Protocol (NTP) server /etc/ntp.conf file:

server { $ntpd{NTPServer} }driftfile /etc/ntp/driftauthenticate no

The NTPServer setting is stored in the ntpd configuration database record, and so can be accessed via the hash accessor$ntpd{NTPServer}.

6.2.1 template-begin and template-end

Each template directory can contain two optional files template-begin and template-end . The template-begin file is always processed as the first file of the template, and the template-end file is always processed as the lastfile.

If the directory does not contain a template-begin file, the contents of/etc/e-smith/templates-default/template-begin is used automatically.

If the directory does not contain a template-end , nothing is appended to the template output. It is mostly usedto provide the closing block for configuration files written in languages such as HTML and PHP, through a link to anentry in the templates-default/ directory.

6.2.2 /etc/e-smith/templates-default

The /etc/e-smith/templates-default directory contains a set of template-begin and template-endfiles for various languages. For example, if your template generates a perl script, you would linktemplate-begin to /etc/e-smith/templates-default/template-begin-perl and automaticallyget the #!/usr/bin/perl -w line and a comment containing the contents of the default template-begin file.

Note: You may also need a templates.metadata configuration file if your generated file needs to be executable.

6.2.3 Template fragment ordering

Template fragments are assembled in ASCII-betical order, with two exceptions: template-begin always comes first,and template-end always comes last. Template fragments are often named to start with a two digit number to make theordering obvious, but this is not required.

6.2.4 Templates for user home directories: templates-user

Most of the templates on the system map to single, fixed output files, such as /etc/hosts. However, templates arealso used to generate configuration files such as mail delivery instructions for users. These templates are stored in the/etc/e-smith/template-user/ tree.

As these templates have a variable output filename, they are expanded using small pieces of Perl code in action scripts.

6.2. The Text::Template module 23


6.2.5 Local site overrides: templates-custom and templates-user-custom

It is possible that the standard templates are not correct for a particular installation, and so the local system administra-tor can override the existing templates by placing files in the templates-custom tree. This is a parallel tree to thenormal templates hierarchy, and is normally empty. There is also a template-user-custom tree for overridingentries in the templates-user tree.

If a templates-custom entry exists for a template, it is merged with the standard templates directory during templateexpansion, using the following rules:

• If a fragment of the same name exists in both templates and templates-custom, the one from templates-customis used, and the one from the standard templates tree is ignored.

• If the fragments in templates-custom have different names from those in templates, they are merged into thetemplate as if they were in the templates directory.

• If the templates-custom entry is a file, rather than a directory, it completely overrides the standard template.

To make this concrete, let’s assume we have the following template structure in/etc/e-smith/templates/etc/book.conf:

10intro30chapter340chapter480synopsis

and in /etc/e-smith/templates-custom/etc/book.conf:

30chapter350chapter5

The resulting template would be processed in this order:

• template-begin from /etc/e-smith/templates-default

• 10intro from /etc/e-smith/templates/etc/book.conf

• 30chapter3 from /etc/e-smith/templates-custom/etc/book.conf

• 40chapter4 from /etc/e-smith/templates/etc/book.conf

• 50chapter5 from /etc/e-smith/templates-custom/etc/book.conf

• 80synopsis from /etc/e-smith/templates/etc/book.conf

• template-end (empty), nominally from /etc/e-smith/templates-default

How to resolve conflicts with standard templates

It is possible that the standard templates may specify behaviour which is not appropriate for your application. In manycases the templates will be driven by configuration database settings which allow their behaviour to be customized,which should be the first thing to check.

In many cases, your application only needs to extend the behaviour of the template by adding one or more fragments.This should be your second option and can be achieved by simply adding your fragment in the correct place in the listof fragments.

In rare cases the standard template specifies a behaviour which conflicts with your application. In these cases, youshould do all of the following:

• Create a templates-custom directory to match the existing one in the templates hierachy.



• Copy the conflicting fragment, and only that fragment, to the templates-custom directory. The fragment shouldhave the same name in both directories. At this point you have not changed the behaviour of the system as thetemplates-custom entry will be preferred, but will behave identically.

• Modify the copy in templates-custom to suit your required behaviour.

• Inform the NethServer team about the problem. Please attach your modified template (or even better, a patchfile) and provide details of why you think that the standard template should be changed.

6.2.6 The expansion of templates

To expand your custom templates to their destination you have to use the following command:

expand-template

where template destination has to be changed with the true path to the configuration file.

For Example you want to add something to the samba configuration, then you have to build a custom template fragmentunder /etc/e-smith/template-custom/etc/samba/smb.conf/ directory and execute the command:

expand-template /etc/samba/smb.conf

6.2.7 Subdirectory templates

It is also possible to split templates into further subdirectories. This can be very useful for evaluating the samefragments in a loop, for example for each virtual domain in httpd.conf or each ibay in smb.conf.

Two examples of this can be found in /etc/e-smith/templates/etc/httpd/conf/httpd.conf/80VirtualHostswhich loops over the /etc/e-smith/templates/etc/httpd/conf/httpd.conf/VirtualHosts/directory, and /etc/e-smith/templates/etc/smb.conf/90ibays which performs a similar loop overthe /etc/e-smith/templates/etc/smb.conf/ibays/ directory.

6.3 Template expansion

The system is designed to ensure consistent and reliable operation, without requiring command-line access. Wheneveran event is signalled, the relevant templates for that event are expanded and the services are notified of the configurationchanges.

Requesting expansion of a template in an event is a simple matter of creating an empty file under thetemplates2expand hierarchy for that event.

See events manual chapter for further information.

6.4 Template permissions and ownership: templates.metadata

Templates are normally expanded to be owned by root and are not executable, which is a reasonable default formost configuration files. However, templates may need to generate configuration files which are owned by a dif-ferent user, or which need to be executable or have other special permissions. This can be done by creating atemplates.metadata file which defines the additional attributes for the expansion.

6.3. Template expansion 25


Note: Configuration files should generally not be writable by any user other than root. In particular, configurationfiles should not normally be writable by the www user as this poses a significant security risk. Installation advicewhich says chmod 777 is almost invariably wrong.

For example, here is the metadata file /etc/e-smith/templates.metadata/etc/ppp/ip-up.local:

UID="root"GID="daemon"PERMS=0755

which sets the group to daemon and makes the script executable. Note that the file is readable by members of thedaemon group, but it is not writable by anyone but root. It is also possible to use the same template to generatemultiple output files, such as in this example:

TEMPLATE_PATH="/etc/sysconfig/network-scripts/route-ethX"OUTPUT_FILENAME="/etc/sysconfig/network-scripts/route-eth1"MORE_DATA={ THIS_DEVICE => "eth1" }FILTER=sub { $_[0] =~ /^#/ ? '' : $_[0] } # Remove comments

The templates.metadata file for route-eth0 just uses eth0 instead of eth1 on the second and third lines. Note alsothe FILTER setting which allows post-processing of the generated template.

There are many examples under /etc/e-smith/templates.metadata/ and the full list of options can beseen with:

perldoc esmith::templates

6.5 Perl API: processTemplate

In rare circumstances you may need to call processTemplate directly. Explicit calls to processTemplate aretypically only used when the output filename is variable:

use esmith::templates;foreach my $name (@names){

[...]processTemplate({

TEMPLATE_PATH => "/etc/myservice/user.conf",OUTPUT_FILENAME => "/etc/myservice/$name.conf"

);[...]

}

bq. Content is available under GNU Free Documentation License 1.3 unless otherwise noted. Original documentfrom: http://wiki.contribs.org/


http://wiki.contribs.org/

CHAPTER 7

Actions and events

7.1 Actions

An action is a program, frequently written in a scripting language, which performs a single task. It is typically anencapsulation of a task usually done by a system administrator, such as editing a configuration file or reconfiguring aservice. Actions are not called directly; they are always called by signalling an event.

The actions are stored in the /etc/e-smith/events/actions/ directory. These actions are then linkedinto the relevant events as the same action may need to be performed in more than one event. To cre-ate a new action called myaction you simply create a program to perform the action myaction and save it as/etc/e-smith/events/actions/myaction . Actions can be written in any programming language, al-though additional platform support is provided for Perl code.

An example action script is:

#!/bin/bash/usr/sbin/lokkit --update

7.1.1 Action script parameters

Action scripts are always called with at least one parameter; the name of the current event. Many action scripts canbe called with a single additional parameter. This parameter is usually a configuration database key, for example theusername being modified. Action scripts rarely require more than two parameters. The details should be stored in theconfiguration database(s) and only the key should be passed to the action scripts. All configuration details must bestored in the configuration databases and the database key passed as the parameter to the action. This allows otherscripts to be added to the event.

Since the system passes the name of the current event as the first parameter, it is often beneficial to write action scriptswhich are polymorphic based on the event name. For example, the code to create a user and the code to modify anexisting user may be only slightly different and may well benefit from being in a single script. Example:

use strict;my $event = $ARGV[0];my $myarg = $ARGV[1];

exit 0;

Note: Whenever possible, avoid to call events from within action scripts.

27


7.1.2 Action code libraries

To promote code reusability and components abstraction some Perl mod-ules are available under /usr/share/perl5/vendor_perl/NethServer/ and/usr/share/perl5/vendor_perl/esmith/. For instance,

NethServer::Password

Secret generation and persistent storage, under /var/lib/nethserver/secrets/.

NethServer::Service Service manager agnostic API. No matter if a service is managed by systemd, Upstart or SysVinit script: use this API to gain control over it.

NethServer::Directory Access to LDAP, service accounts and ACL management, low-level user and group manage-ment.

NethServer::MailServer Obtain accounts and mail addresses relations. Manage IMAP ACLs.

esmith::templates Template processing and expansion.

esmith::events Event execution and tracking.

For more informations about a specific module, refer its perldoc documentation.

7.2 Events

Events are a mechanism which allows the system to trigger a set of actions in response to actual events that happen onthe system. When one of the users interfaces modifies the configuration databases, it must signal an event to regeneratethe various server application configuration files according to the new configuration.

Note: The user interface must never modify configuration files directly. Neither should to the administrator fromcommand line.

Each event is associated with a list of actions which should be performed when the event occurs and is de-fined as a subdirectory of /etc/e-smith/events/ containing symbolic links to the appropriate actions,loosely modelled after the ‘’System V init’‘mechanism for starting servers. For example, if you examine the/etc/e-smith/events/interface-update directory:

[root@nsrv actions]# ll /etc/e-smith/events/interface-update/total 8lrwxrwxrwx. 1 root root 34 Feb 6 11:19 S04interface-config-adjust -> ../actions/interface-config-adjustlrwxrwxrwx. 1 root root 33 Feb 6 11:19 S25interface-config-reset -> ../actions/interface-config-resetlrwxrwxrwx. 1 root root 33 Feb 6 11:19 S30interface-config-write -> ../actions/interface-config-writelrwxrwxrwx. 1 root root 35 Feb 6 11:19 S70interface-config-restart -> ../actions/interface-config-restartlrwxrwxrwx. 1 root root 36 Feb 6 11:19 S75interface-config-hostname -> ../actions/interface-config-hostnamedrwxr-xr-x. 2 root root 4096 Feb 6 11:20 services2adjustdrwxr-xr-x. 3 root root 4096 Dec 18 11:17 templates2expand

The symbolic links are given prefixes such as S15, S85, etc. to specify the order in which the actions should beexecuted in a similar manner to the System V init mechanism. You can change the actions performed by an eventby changing the links in the event directory. You can also create a new event by creating another subdirectory of/etc/e-smith/events/.

7.2.1 Implicit actions

Most events contain two common tasks: expanding various templates and adjusting (e.g. restarting) the relevantservices. For this reason, two implicit actions are included in all events. These implicit actions mean that additional

28 Chapter 7. Actions and events


code does not need to be written to perform these common tasks. The implicit actions are represented by entries in theservices2adjust/ and templates2expand/ subdirectories.

services2adjust

The services2adjust/ directory contains links mapping a specific service to the action to perform on that service.For example, if signalling the event in question requires that the ntpd service is restarted, you simply include the linkntpd -> restart in the services2adjust directory. The implicit action services2adjust would then restart thentpd service. As an example, the services2adjust/ directory for the nethserver-httpd-update event isshown below:

# ls> l /etc/e-smith/events/nethserver-httpd-update/services2adjust/total 0lrwxrwxrwx. 1 root root 7 Oct 2 09:05 httpd -> restart

templates2expand

The templates2expand/ directory contains a list of the configuration files which need to be regenerated fromtheir templates. This list consists of a collection of empty files with the same file name as the configuration fileto be expanded and in a heirarchy mirroring their location on the system. For example, to expand templates forthe /etc/samba/smb.conf configuration file, simply include the empty file etc/samba/smb.conf in thetemplates2expand/ directory of the relevant event.

Order of implicit actions

The implicit actions are implemented by inserting the action script generic_template_expand early in the listof actions to be run in an event and the adjust-services action near the end of the list. You should normally linkyour action scripts in the range S10 to S80 so that they occur after templates2expand and before services2adjust.

Note: The generic_template_expand action is currently run at S05 and adjust-services is run at S90.

7.2.2 Signalling events

The signal-event program takes an event name as an argument, and executes all of the actions in that event,providing the event name as the first parameter and directing all output to the system log. It works by listing theentries in the event directory and executing them in sequence. So for example, the command:

signal-event interface-update

will perform all the actions associated with the interface-update event, which is defined by the contents of the/etc/e-smith/events/interface-update/ directory.

Events with arguments

So far we have described the following general principle throughout the system; changes are made by altering thedatabase values, then signalling events. The actions triggered by each event typically regenerate entire configurationfiles, taking into account the latest configuration information.

However, some changes are best made incrementally. For example, consider the user-create event. One of its actionsupdates the LDAP directory, which it could do by deleting all of the users and recreating them based on the updated

7.2. Events 29


accounts database. However, this is inefficient and would lose any additional LDAP attributes which may havebeen stored. It would be better to simply add the new user incrementally, using the default LDAP schema.

But how is the action code to know which user was just added? The new username is passed as an argument to the user-create event. This way the action programs triggered by the user-create event have a choice. They can either ignorethe username argument and regenerate their output based on the updated list of accounts, or they can pay attentionto the username argument, retrieve the rest of the information about the new user from the accounts database, andperform the incremental work to add the user.

Note: Action scripts should normally take at most two arguments. The first is always the event name. The secondoptional argument is a key into one of the databases. Events are not function calls.

Events are not currently serialized. In most cases overlapping events will not cause issues, but caution should beexercised when events are signalled from programs.

7.2.3 Standard events and their arguments

The table below summarises the key NethServer events and their argument if required. Remember, each action scriptis always called with the event name as the first argument. The arguments listed in this table are provided as the secondargument.

Event Arguments Descriptioncertificate-update The server public key certificate has been updatedfstab-update Update /etc/fstab according fo fstab key and remount all fileystemsgroup-create Group key Called when a group is createdgroup-delete Group key Called when a group is deletedgroup-modify Group key Called when a group is modifiedgroup-create-pseudonyms Signalled when the automatic creation of group email address is requiredhost-create Host key Called when a host is createdhost-delete Host key Called when a host is deletedhost-modify Host key Called when a host is modifiedhostname-modify Called when the SystemName or DomainName keys have been modifiedibay-create Shared folder key Called when a shared folder is createdibay-delete Shared folder key Called when a shared folder is deletedibay-modify Shared folder key Called when a shared folder is modifiedinterface-update Called when a network interface configuration is updated in networks dblogrotate-update Change default log retention and rotation policiestrusted-networks-update The set of trusted networks is changedmigration-import Path to migration directory Import migration data from the given directorypassword-expired Username, expire date The given username password will expire on expiredatepassword-modify User key Called when a user password is modifiedpassword-policy-update User key Called when the system password policy has been changedpost-backup-config Called after configuration backup endpost-backup-data Called after data backup endpost-restore-config Called after restore of configurationpost-restore-data Called after restore of datapre-backup-config The pre-backup-config event creates consistent system state for the backuppre-backup-data The pre-backup-data event creates consistent system state for the backuppre-restore-config Called before restore of configurationpre-restore-data Called before restore of data

Continued on next page



Table 7.1 – continued from previous pageEvent Arguments Descriptionpseudonym-create Pseudonym key Called when a pseudonym is createdpseudonym-delete Pseudonym key Called when a pseudonym is deletedpseudonym-modify Pseudonym key Called when a pseudonym is modifieduser-create User key Called when a user is createduser-delete User key Called when a user is deleteduser-modify User key Called when a user is modifieduser-create-pseudonyms User key Called when the automatic creation of user’s email address(es) is requireduser-lock User key Called when a user account is lockeduser-unlock User key Called when a user account is unlockedsystem-initialization Initialize all system after installation

Handling deletions

When adding a user, the user is created in the accounts database, and various actions, such as creating the Linuxaccount, are performed in the user-create event. However, when deleting a user, we want to maintain theaccounts database entry for as long as possible, in case there is information which the actions in the user-deleteevent might need in order to cleanly delete the users. The system convention for handling deletions is:

• Change the type of the entry to mark it as being in the process of being deleted e.g. a’‘user’‘entry becomesa’‘user-deleted’‘entry.

• Signal the relevant deletion event - e.g.’‘user-delete’‘

• Remove the entry from the database, but only if the event succeeds. With this approach, the action scripts candecide whether to ignore the’‘user-deleted” entries when performing their tasks.

7.2.4 Event logs

Warning: Output of event logs will be soon refactored!

All events, and all actions run by the event, are logged to the messages system log. Here is an example action log,which has been formatted onto multiple lines to enhance readability:

Feb 2 13:22:33 gsxdev1 esmith::event[4525]:S65sshd-conf=action|Event|remoteaccess-update|Action|S65sshd-conf|Start|1138846952 730480|End|1138846953 66768|Elapsed|0.336288

From this single log, we can see the action script name, which event it was called in, when it started, ended and howlong it took (0.34 seconds). Now, let’s add an action script which always fails and signal the event again:

Feb 2 16:11:54 gsxdev1 esmith::event[4787]:S99false=action|Event|remoteaccess-update|Action|S99false|Start|1138857114 58910|End|1138857114 81920|Elapsed|0.02301|Status|256

7.2. Events 31


Note that this log has a new field Status, which is added if the action script returns a false (non-zero) exit status.Suppressing the Status field when it is zero (success) makes it much easier to find failed actions in the logs.

Warning: If an action script fails, the entire event fails. The other actions scripts in the event are run, but thewhole event is marked as having failed.

7.2.5 System validators

System validators provide an extensible UI-independent data validation layer.

On one hand UI implements fast grammar and/or syntax checks on input data. On the other, the system validatorsperforms in-depth system consistency checks.

Design

Validators have a behaviour very similar to events.

• A validator is a directory inside /etc/e-smith/validators.

• Each validator directory has a descriptive name, eg. user-name for a validator which validate a new user name.

• A validator is composed by an arbitrary number of actions saved inside/etc/e-smith/validators/actions directory and linked inside validator directory.

• A success validation occurs when all scripts return 0 (success validation) or at least one script returns 2 (sufficientvalid condition).

A validator action are always called with a single parameter which is the value to be validated. Actions must returnone of these exit values:

• 0: successful validation

• 1: validation failed

• 2: sufficient validation

• other value: specific error state

When a script returns 2 (sufficient validation) no further script will be processed.

Inside nethserver-devtools package there is validator_actions() function which help creating links to actionsjust like event_actions function. See perldoc esmith::Build::CreateLinks for details.

Invoking a validator:

validate

Eg:

validate user-name goofy

h2. Implementation

See #303.


CHAPTER 8

Services

A service is a software which usually runs in background. The system will ensure service status accordingly to itsconfiguration. A service in configuration database is something like this:

httpd=servicestatus=enabledaccess=publicTCPPorts=80,443

Where httpd is the service name and status tells the system if the service should be enabled or disabled.

When the status property is switched between enabled/disabled state, the change will be reflected into runlevel con-figuration using chkconfig command. If both Upstart and SysV scripts are present, Upstart has the precedence andSysV script is disabled. For example see httpd-admin service.

This is what runlevel-adjust event and action do for all configured services. There is also another action calledadjust-services which does the same thing for services registered on a single event.

A service without a record in the configuration database is ignored and can be manually manged using chkconfigand service commands. See Add a new service.

8.1 Control a service

Enable a service:

config setprop myservice status enabledsignal-event runlevel-adjust

Disable a service:

config setprop myservice status disabledsignal-event runlevel-adjust

Where myservice is the service name to be enabled or disabled.

8.2 Access network service

A network service is a service running on the server which expose UDP or TCP ports. Ports can be listed in followingproperties:

• TCPPort: a single TCP port

33


• TCPPorts: a comma separated list of TCP ports

• UDPPort: a single UDP port

• UDPPorts: a comma separated list of UDP ports

If both TCPPort and TCPPorts properties are set, TCPPorts has the precedence. If both UDPPort and TCPPortsproperties are set, UDPPorts has the precedence.

A service can be accessible from public or private LAN. This configuration is saved on access property. The propertycan have one of the following values:

• none: the service is accessible only from localhost, no port is open

• private: the service is accessible only from green interfaces

• public: the service is accessible from green and red interfaces, but no blue and orange

Example of a service with UDP port 1122 open to the Internet:

config setprop myservice status enabled UDPPort 1122 access public

Example of a service with TCP ports 1122 an 2233 open to local network:

config setprop myservice status enabled TCPPorts 1122,2233 access private

The ports are opened only if the status property is set to enabled.

8.2.1 Custom access

Each network service can have one or both of following properties:

• AllowHosts: listed hosts can always access the service

• DenyHosts: listed hosts can never access the service

Both properties can be a list of IPs or CIDR networks and are honored only if access is seto to private or public

8.3 Add a new service

Any software can configure the init system using the standard chkconfig command. This approach always workfor third-party software.

On the other hand, if the service must be controlled by NethServer, create a new record inside configuration database:

config set myservice service status enabled

Where myservice is the name of the new service.

Make sure also there are defaults values inside the directory /etc/e-smith/db/configuration/defaults:if the key is present inside the configuration database, but not inside defaults, the service will be stopped. Given theabove example, create these files:

mkdir -p /etc/e-smith/db/configuration/defaults/myserviceecho "service" > /etc/e-smith/db/configuration/defaults/myservice/typeecho "enabled" > /etc/e-smith/db/configuration/defaults/myservice/status

Signal the new service to the system:

signal-event runlevel-adjust

34 Chapter 8. Services


8.4 Add a new network service

If a service not controlled by NethServer needs one or more open ports, use the TCPPort(s) or UDPPort(s) prop todeclare the port(s) and signal the firewall to open it:

config set fw_myservice service status enabled TCPPort 12345 access privatesignal-event firewall-adjust

Otherwise, if the service is controlled by NethServer, you can add the properties directly to the service key. For theservice myservice on above example:

config set myservice service status enabled TCPPort 12345 access privatesignal-event firewall-adjust

See nethserver-firewall-base.

8.4. Add a new network service 35


36 Chapter 8. Services

Documents

NethServer Documentation · 2019. 4. 2. · 49 CUPS 145 49.1 Conﬁguration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145 49.2 Printer