| 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 *** |