1 #ifndef MASTER_SERVICE_H 2 #define MASTER_SERVICE_H 3 4 #include "net.h" 5 6 #include <unistd.h> /* for getopt() opt* variables */ 7 #include <stdio.h> /* for getopt() opt* variables in Solaris */ 8 9 enum master_service_flags { 10 /* stdin/stdout already contains a client which we want to serve */ 11 MASTER_SERVICE_FLAG_STD_CLIENT = 0x01, 12 /* this process is currently running standalone without a master */ 13 MASTER_SERVICE_FLAG_STANDALONE = 0x02, 14 /* Log to configured log file instead of stderr. By default when 15 _FLAG_STANDALONE is set, logging is done to stderr. */ 16 MASTER_SERVICE_FLAG_DONT_LOG_TO_STDERR = 0x04, 17 /* Service is going to do multiple configuration lookups, 18 keep the connection to config service open. Also opens the config 19 socket before dropping privileges. */ 20 MASTER_SERVICE_FLAG_KEEP_CONFIG_OPEN = 0x08, 21 /* Don't read settings, but use whatever is in environment */ 22 MASTER_SERVICE_FLAG_NO_CONFIG_SETTINGS = 0x10, 23 /* Use MASTER_LOGIN_NOTIFY_FD to track login overflow state */ 24 MASTER_SERVICE_FLAG_TRACK_LOGIN_STATE = 0x40, 25 /* If master sends SIGINT, don't die even if we don't have clients */ 26 MASTER_SERVICE_FLAG_NO_IDLE_DIE = 0x80, 27 /* Show number of connections in process title 28 (only if verbose_proctitle setting is enabled) */ 29 MASTER_SERVICE_FLAG_UPDATE_PROCTITLE = 0x100, 30 /* Don't initialize SSL context automatically. */ 31 MASTER_SERVICE_FLAG_NO_SSL_INIT = 0x400, 32 /* Don't create a data stack frame between master_service_init() and 33 master_service_init_finish(). By default this is done to make sure 34 initialization doesn't unnecessarily use up memory in data stack. */ 35 MASTER_SERVICE_FLAG_NO_INIT_DATASTACK_FRAME = 0x800, 36 /* Don't connect at startup to the stats process. */ 37 MASTER_SERVICE_FLAG_DONT_SEND_STATS = 0x1000, 38 /* Service supports STARTTLS-like feature. SSL server must be 39 initialized even if there are no ssl=yes listeners. */ 40 MASTER_SERVICE_FLAG_HAVE_STARTTLS = 0x2000, 41 }; 42 43 struct master_service_connection_proxy { 44 /* only set if ssl is TRUE */ 45 const char *hostname; 46 const char *cert_common_name; 47 const unsigned char *alpn; 48 unsigned int alpn_size; 49 50 bool ssl:1; 51 bool ssl_client_cert:1; 52 }; 53 54 struct master_service_connection { 55 /* fd of the new connection. */ 56 int fd; 57 /* fd of the socket listener. Same as fd for a FIFO. */ 58 int listen_fd; 59 /* listener name as in configuration file, or "" if unnamed. */ 60 const char *name; 61 62 /* Original client/server IP/port. Both of these may have been changed 63 by the haproxy protocol. */ 64 struct ip_addr remote_ip, local_ip; 65 in_port_t remote_port, local_port; 66 67 /* The real client/server IP/port, unchanged by haproxy protocol. */ 68 struct ip_addr real_remote_ip, real_local_ip; 69 in_port_t real_remote_port, real_local_port; 70 71 /* filled if connection is proxied */ 72 struct master_service_connection_proxy proxy; 73 74 /* This is a connection proxied wit HAproxy (or similar) */ 75 bool proxied:1; 76 77 /* This is a FIFO fd. Only a single "connection" is ever received from 78 a FIFO after the first writer sends something to it. */ 79 bool fifo:1; 80 /* Perform immediate SSL handshake for this connection. Currently this 81 needs to be performed explicitly by each service. */ 82 bool ssl:1; 83 84 /* Internal: master_service_client_connection_accept() has been 85 called for this connection. */ 86 bool accepted:1; 87 }; 88 89 typedef void 90 master_service_connection_callback_t(struct master_service_connection *conn); 91 92 /* If kill==TRUE, the callback should kill one of the existing connections 93 (likely the oldest). If kill==FALSE, it's just a request to check what is 94 the creation timestamp for the connection to be killed. Returns TRUE if 95 a connection was/could be killed, FALSE if not. */ 96 typedef bool 97 master_service_avail_overflow_callback_t(bool kill, struct timeval *created_r); 98 99 extern struct master_service *master_service; 100 101 const char *master_service_getopt_string(void); 102 103 /* Start service initialization. */ 104 struct master_service * 105 master_service_init(const char *name, enum master_service_flags flags, 106 int *argc, char **argv[], const char *getopt_str); 107 /* Call getopt() and handle internal parameters. Return values are the same as 108 getopt()'s. */ 109 int master_getopt(struct master_service *service); 110 /* Returns TRUE if str is a valid getopt_str. Currently this only checks for 111 duplicate args so they aren't accidentally added. */ 112 bool master_getopt_str_is_valid(const char *str); 113 /* Parser command line option. Returns TRUE if processed. */ 114 bool master_service_parse_option(struct master_service *service, 115 int opt, const char *arg); 116 /* Finish service initialization. The caller should drop privileges 117 before calling this. This also notifies the master that the service was 118 successfully started and there shouldn't be any service throttling even if 119 it crashes afterwards, so this should be called after all of the 120 initialization code is finished. */ 121 void master_service_init_finish(struct master_service *service); 122 123 /* import_environment is a space-separated list of environment keys or 124 key=values. The key=values are immediately added to the environment. 125 All the keys are added to DOVECOT_PRESERVE_ENVS environment so they're 126 preserved by master_service_env_clean(). */ 127 void master_service_import_environment(const char *import_environment); 128 /* Clean environment from everything except the ones listed in 129 DOVECOT_PRESERVE_ENVS environment. */ 130 void master_service_env_clean(void); 131 132 /* Initialize logging. Only the first call changes the actual logging 133 functions. The following calls change the log prefix. */ 134 void master_service_init_log(struct master_service *service); 135 /* Initialize/change log prefix to the given log prefix. */ 136 void master_service_init_log_with_prefix(struct master_service *service, 137 const char *prefix); 138 /* Initialize/change log prefix to "configured_name(my_pid): " */ 139 void master_service_init_log_with_pid(struct master_service *service); 140 /* Initialize stats client (if it's not already initialized). This is called 141 automatically if MASTER_SERVICE_FLAG_SEND_STATS is enabled. If 142 silent_notfound_errors is set, connect() errors aren't logged if they're 143 happening because the stats service isn't running. */ 144 void master_service_init_stats_client(struct master_service *service, 145 bool silent_notfound_errors); 146 147 /* If set, die immediately when connection to master is lost. 148 Normally all existing clients are handled first. */ 149 void master_service_set_die_with_master(struct master_service *service, 150 bool set); 151 /* Call the given when master connection dies and die_with_master is TRUE. 152 The callback is expected to shut down the service somewhat soon or it's 153 done forcibly. If NULL, the service is stopped immediately. */ 154 void master_service_set_die_callback(struct master_service *service, 155 void (*callback)(void)); 156 /* "idle callback" is called when master thinks we're idling and asks us to 157 die. We'll do it only if the idle callback returns TRUE. This callback isn't 158 even called if the master service code knows that we're handling clients. */ 159 void master_service_set_idle_die_callback(struct master_service *service, 160 bool (*callback)(void)); 161 /* Call the given callback when there are no available connections and master 162 has indicated that it can't create any more processes to handle requests. */ 163 void master_service_set_avail_overflow_callback(struct master_service *service, 164 master_service_avail_overflow_callback_t *callback); 165 166 /* Set maximum number of clients we can handle. Default is given by master. */ 167 void master_service_set_client_limit(struct master_service *service, 168 unsigned int client_limit); 169 /* Returns the maximum number of clients we can handle. */ 170 unsigned int master_service_get_client_limit(struct master_service *service); 171 /* Returns how many processes of this type can be created before reaching the 172 limit. */ 173 unsigned int master_service_get_process_limit(struct master_service *service); 174 /* Returns service { process_min_avail } */ 175 unsigned int master_service_get_process_min_avail(struct master_service *service); 176 /* Returns the service's idle_kill timeout in seconds. Normally master handles 177 sending the kill request when the process has no clients, but some services 178 with permanent client connections may need to handle this themselves. */ 179 unsigned int master_service_get_idle_kill_secs(struct master_service *service); 180 181 /* Set maximum number of client connections we will handle before shutting 182 down. */ 183 void master_service_set_service_count(struct master_service *service, 184 unsigned int count); 185 /* Returns the number of client connections we will handle before shutting 186 down. The value is decreased only after connection has been closed. */ 187 unsigned int master_service_get_service_count(struct master_service *service); 188 /* Return the number of listener sockets. */ 189 unsigned int master_service_get_socket_count(struct master_service *service); 190 /* Returns the name of the listener socket, or "" if none is specified. */ 191 const char *master_service_get_socket_name(struct master_service *service, 192 int listen_fd); 193 194 /* Returns configuration file path. */ 195 const char *master_service_get_config_path(struct master_service *service); 196 /* Returns PACKAGE_VERSION or NULL if version_ignore=yes. This function is 197 useful mostly as parameter to module_dir_load(). */ 198 const char *master_service_get_version_string(struct master_service *service); 199 /* Returns name of the service, as given in name parameter to _init(). */ 200 const char *master_service_get_name(struct master_service *service); 201 /* Returns name of the service, as given in the configuration file. For example 202 service name=auth, but configured_name=auth-worker. This is preferred in 203 e.g. log prefixes. */ 204 const char *master_service_get_configured_name(struct master_service *service); 205 206 /* Start the service. Blocks until finished */ 207 void master_service_run(struct master_service *service, 208 master_service_connection_callback_t *callback) 209 ATTR_NULL(2); 210 /* Stop a running service. */ 211 void master_service_stop(struct master_service *service); 212 /* Stop once we're done serving existing new connections, but don't accept 213 any new ones. */ 214 void master_service_stop_new_connections(struct master_service *service); 215 /* Returns TRUE if we've received a SIGINT/SIGTERM and we've decided to stop. */ 216 bool master_service_is_killed(struct master_service *service); 217 /* Returns TRUE if our master process is already stopped. This process may or 218 may not be dying itself. Returns FALSE always if the process was started 219 standalone. */ 220 bool master_service_is_master_stopped(struct master_service *service); 221 222 /* Send command to anvil process, if we have fd to it. */ 223 void master_service_anvil_send(struct master_service *service, const char *cmd); 224 /* Call to accept the client connection. Otherwise the connection is closed. */ 225 void master_service_client_connection_accept(struct master_service_connection *conn); 226 /* Used to create "extra client connections" outside the common accept() 227 method. */ 228 void master_service_client_connection_created(struct master_service *service); 229 /* Call whenever a client connection is destroyed. */ 230 void master_service_client_connection_destroyed(struct master_service *service); 231 232 /* Deinitialize the service. */ 233 void master_service_deinit(struct master_service **service); 234 /* Deinitialize the service for a forked child process. Currently, the only 235 difference with master_service_deinit() is that lib_deinit() and 236 lib_signals_deinit() are not called. 237 */ 238 void master_service_deinit_forked(struct master_service **_service); 239 240 /* Returns TRUE if line contains compatible service name and major version. 241 The line is expected to be in format: 242 VERSION <tab> service_name <tab> major version <tab> minor version */ 243 bool version_string_verify(const char *line, const char *service_name, 244 unsigned major_version); 245 /* Same as version_string_verify(), but return the minor version. */ 246 bool version_string_verify_full(const char *line, const char *service_name, 247 unsigned major_version, 248 unsigned int *minor_version_r); 249 250 #endif 251