Commit | Line | Data |
---|---|---|
61ec970d PH |
1 | $Cambridge: exim/src/OS/os.Configuring,v 1.1 2004/10/06 15:07:39 ph10 Exp $ |
2 | ||
3 | Configuring Exim for different Operating Systems | |
4 | ------------------------------------------------ | |
5 | ||
6 | These notes describe the way in which Exim is configured at the C program level | |
7 | for different operating systems. The normal configuration options that apply | |
8 | independently of the operating system are specified by creating files in the | |
9 | Local directory, as described in chapter 4 of the manual. | |
10 | ||
11 | These notes cover the os.* files in the OS directory, and contain information | |
12 | for people who want to port the program to some new OS, or to modify the | |
13 | configuration for an existing port. If you are just wanting to compile Exim on | |
14 | a system that it already knows about, you do not need to read further unless | |
15 | there are problems. | |
16 | ||
17 | The os.c-<ostype> files | |
18 | ----------------------- | |
19 | ||
20 | There may be an os.c-<ostype> file for each operating system, but for many of | |
21 | them it is not necessary. No error occurs is there isn't one. There is a | |
22 | generic file called os.c which contains code that is common to two or more OS | |
23 | for setting a restarting or a non-restarting signal, for computing the load | |
24 | average, and for finding all the network interface addresses. A few OS have | |
25 | their own individual code for one or more of these. When they do, the code is | |
26 | put into an os.c-<ostype> file, which also defines a macro such as | |
27 | OS_RESTARTING_SIGNAL (for example) to cut out the common code in the generic | |
28 | os.c. | |
29 | ||
30 | The os.h-<ostype> files | |
31 | ----------------------- | |
32 | ||
33 | For each OS that Exim knows about, there is an os.h-<ostype> file, where | |
34 | <ostype> is the OS name. The relevant file is included as a C header file for | |
35 | all Exim compilation by pointing a symbolic link called os.h at it from the | |
36 | build directory. The settings are as follows: | |
37 | ||
38 | The select() function | |
39 | --------------------- | |
40 | ||
41 | There is a difference in the data type for the second argument to the select() | |
42 | function in some OS. The macro SELECT_ARG2_TYPE can be used to define the type. | |
43 | If it is not defined in os.h, then it is defaulted to fs_set in exim.h. | |
44 | ||
45 | The dn_expand() function | |
46 | ------------------------ | |
47 | ||
48 | There is a difference in the data type for the fourth argument to the | |
49 | dn_expand() function in some OS. The macro DN_EXPAND_ARG4_TYPE can be used to | |
50 | define the type. If it is not defined in os.h, then it is defaulted to char * | |
51 | in exim.h. | |
52 | ||
53 | The h_errno variable | |
54 | -------------------- | |
55 | ||
56 | If NEED_H_ERRNO is defined, then a definition of the form | |
57 | ||
58 | extern int h_errno | |
59 | ||
60 | is included in the compiled code of Exim. | |
61 | ||
62 | The strerror() function | |
63 | ----------------------- | |
64 | ||
65 | Most systems provide the ANSI standard strerror() function; older systems may | |
66 | instead have an errlist[] variable in which to look up error texts. Defining | |
67 | STRERROR_FROM_ERRLIST causes Exim to build its own strerror() function that | |
68 | mimics the ANSI function by lookup up the error code in errlist. | |
69 | ||
70 | Truncating files | |
71 | ---------------- | |
72 | ||
73 | The fcntl() option for truncating the length of a file is called F_FREESP in | |
74 | most systems; in some, however, it is called O_TRUNC. Some os.h files define | |
75 | F_FREESP to be O_TRUNC for this reason. | |
76 | ||
77 | Finding local interfaces | |
78 | ------------------------ | |
79 | ||
80 | The SIOCGIFCONF ioctl for finding local interfaces behaves differently on BSD | |
81 | systems. It returns a vector of ifreq blocks containing sockaddr structures | |
82 | that can be longer than their sizeof definition, making the returned ifreq | |
83 | blocks longer than their sizeof definitions. BSD sockaddrs structures contain | |
84 | an sa_len field giving the actual size. To cope with difference, there is a | |
85 | macro called HAVE_SA_LEN. If it is defined, code that works on BSD systems is | |
86 | used. Otherwise, the objects returned by SIOCGIFCONF are assumed to be of | |
87 | length sizeof(struct ifreq). | |
88 | ||
89 | On some operating systems, the SIOCGIFCONF ioctl returns the IP addresses | |
90 | with the list of interfaces, and there is no need to call SIOCGIFADDR for each | |
91 | individual address. Mostly, making the second call does no harm, but on Linux | |
92 | when there are IP aliases, it causes things to go wrong. This also happens on | |
93 | BSDI. Therefore, there is now a macro to cut it out, called | |
94 | SIOCGIFCONF_GIVES_ADDR. | |
95 | ||
96 | Note that, if IPv6 support is configured, Exim cannot find the IPv6 addresses | |
97 | on local interfaces by itself. You need to set the local_interfaces option in | |
98 | this situation. | |
99 | ||
100 | Computing load averages | |
101 | ----------------------- | |
102 | ||
103 | There are several different ways that load averages are computed. One-off code | |
104 | is put in the os.c-<ostype>, but several OS use similar methods, and these | |
105 | are coded in the generic os.c, using a number of parameters to make variations | |
106 | between OS. | |
107 | ||
108 | Sometimes the load average is not available to unprivileged callers. If | |
109 | LOAD_AVG_NEEDS_ROOT is set, Exim ensures that it is root before trying to | |
110 | obtain a load average value. | |
111 | ||
112 | (1) If HAVE_BSD_GETLOADAVG is defined, Exim uses a simple call to the | |
113 | getloadavg() function. | |
114 | ||
115 | (2) If HAVE_KSTAT is defined, Exim uses the kstat package as found in Solaris 2 | |
116 | (but nowhere else as yet). It uses some supplementary definitions: | |
117 | ||
118 | LOAD_AVG_KSTAT the kstat to use | |
119 | LOAD_AVG_KSTAT_MODULE the module to access | |
120 | LOAD_AVG_KSTAT_SYMBOL the symbol containing the value we want | |
121 | LOAD_AVG_KSTAT_FIELD the field identity | |
122 | ||
123 | (3) If HAVE_DEV_KMEM is defined, Exim reads load average values from the | |
124 | /dev/kmem device. It uses some supplementary definitions: | |
125 | ||
126 | LOAD_AVG_TYPE the data type | |
127 | LOAD_AVG_SYMBOL the symbol to look up | |
128 | KERNEL_PATH the name of the kernel | |
129 | FSCALE a scaling factor | |
130 | ||
131 | Sometimes FSCALE is defined in system headers so need not be defined in the | |
132 | os.h-<ostype> file. | |
133 | ||
134 | Glibc systems and IP options | |
135 | ---------------------------- | |
136 | ||
137 | The code for inspecting IP options is the same in all OS except for systems | |
138 | using glibc (e.g. Linux), which uses a different structure to return data from | |
139 | getsockopt(). To handle this, there is a macro called | |
140 | ||
141 | GLIBC_IP_OPTIONS | |
142 | ||
143 | which should be set for Linux (in os.h-Linux) and any other operating system | |
144 | that uses glibc. | |
145 | ||
146 | Options for statvfs() | |
147 | --------------------- | |
148 | ||
149 | The following settings apply to the compilation of the Exim monitor as well as | |
150 | to the main Exim binary. | |
151 | ||
152 | #undefine HAVE_STATFS | |
153 | ||
154 | Exim has options for checking the amount of space in the spool partition | |
155 | before accepting a message, and the monitor has the ability to display a | |
156 | stripchart of the percentage fullness of a particular disc partition, usually | |
157 | /var/spool/mail. The standard way of finding out the data is to call the | |
158 | statvfs() function, but some operating systems use statfs() and some may not | |
159 | have the ability at all. The Exim code uses STATVFS() for this function and | |
160 | this gets defined appropriately. HAVE_STATFS is defined before including the | |
161 | os.h file; undefining it suppresses the code for checking a partition in the | |
162 | main binary, and for monitoring disc partition in the monitor. | |
163 | ||
164 | When HAVE_STATFS is defined, the distinction between statvfs() and statfs() is | |
165 | made by checking HAVE_SYS_STATVFS_H. If it is defined, then sys/statvfs.h is | |
166 | included. Otherwise, STATVFS() is defined as a macro for statfs(), and some | |
167 | further includes are done, according to the following definitions: | |
168 | ||
169 | #define HAVE_SYS_MOUNT_H | |
170 | #define HAVE_VFS_H | |
171 | ||
172 | Each of those definitions causes the inclusion of the corresponding system | |
173 | header file in the Exim monitor compilation. For example, the first one causes | |
174 | ||
175 | #include <sys/mount.h> | |
176 | ||
177 | to be obeyed. Different systems may require different combinations of these | |
178 | headers. | |
179 | ||
180 | The sys/resource.h header | |
181 | ------------------------- | |
182 | ||
183 | One OS does not have the sys/resource.h header. If NO_SYS_RESOURCE_H is defined | |
184 | in an os.h-<ostype> file, then the #include for this header is skipped in | |
185 | exim.h. | |
186 | ||
187 | The crypt_h header | |
188 | ------------------ | |
189 | ||
190 | Some OS require crypt.h to be included to get a prototype for the crypt() | |
191 | function. This is needed only when compiling with AUTH support. If CRYPT_H is | |
192 | defined, then this header is included. | |
193 | ||
194 | mmap() support | |
195 | -------------- | |
196 | ||
197 | The CDB support includes the option of handling file operations by using | |
198 | mmap()/munmap(). This gives a reasonable performance increase which will | |
199 | probably scale over multiple processes (since the files are mapped read-only | |
200 | shared). The vast majority of modern operating systems will support mmap | |
201 | (certainly in the simplified way that it is being used here). For example any | |
202 | BSD 4.x derived or POSIX compliant system will support it, as will pretty much | |
203 | any system using dynamically shared link libraries. | |
204 | ||
205 | If the OS is believed to support mmap() then the symbol HAVE_MMAP is defined. | |
206 | Not all systems that support mmap will have had their config files updated to | |
207 | reflect this. Currently Linux, Sun, BSD and SGI/mips systems have been updated. | |
208 | ||
209 | *** End *** |