master-service.h revision 754896551f0422cda5d78500b26700eec5343c5b
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen#include <unistd.h> /* for getopt() opt* variables */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen#include <stdio.h> /* for getopt() opt* variables in Solaris */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch /* stdin/stdout already contains a client which we want to serve */
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen /* this process is currently running standalone without a master */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Log to configured log file instead of stderr. By default when
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen _FLAG_STANDALONE is set, logging is done to stderr. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen MASTER_SERVICE_FLAG_DONT_LOG_TO_STDERR = 0x04,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Service is going to do multiple configuration lookups,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen keep the connection to config service open. Also opens the config
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen socket before dropping privileges. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Don't read settings, but use whatever is in environment */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen MASTER_SERVICE_FLAG_NO_CONFIG_SETTINGS = 0x10,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Use MASTER_LOGIN_NOTIFY_FD to track login overflow state */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* If master sends SIGINT, don't die even if we don't have clients */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Show number of connections in process title
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen (only if verbose_proctitle setting is enabled) */
b8835b8a21c617ceb82ddc5a176243faf36aa8f7Timo Sirainen /* SSL settings are always looked up when we have ssl listeners.
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen This flag enables looking up SSL settings even without ssl
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen listeners (i.e. the service does STARTTLS). */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Don't initialize SSL context automatically. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Don't create a data stack frame between master_service_init() and
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen master_service_init_finish(). By default this is done to make sure
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen initialization doesn't unnecessarily use up memory in data stack. */
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen MASTER_SERVICE_FLAG_NO_INIT_DATASTACK_FRAME = 0x800
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen /* only set if ssl is TRUE */
4ee00532a265bdfb38539d811fcd12d51210ac35Timo Sirainen const unsigned char *alpn;
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* fd of the new connection. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* fd of the socket listener. Same as fd for a FIFO. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* listener name as in configuration file, or "" if unnamed. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch /* Original client/server IP/port. Both of these may have been changed
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch by the haproxy protocol. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch /* The real client/server IP/port, unchanged by haproxy protocol. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* filled if connection is proxied */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch /* This is a connection proxied wit HAproxy (or similar) */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* This is a FIFO fd. Only a single "connection" is ever received from
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen a FIFO after the first writer sends something to it. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Perform immediate SSL handshake for this connection. Currently this
df1713bd29d29a3e3f3ebfdf05f929525825a7d3Timo Sirainen needs to be performed explicitly by each service. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen /* Internal: master_service_client_connection_accept() has been
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen called for this connection. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenmaster_service_connection_callback_t(struct master_service_connection *conn);
df1713bd29d29a3e3f3ebfdf05f929525825a7d3Timo Sirainenconst char *master_service_getopt_string(void);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Start service initialization. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenmaster_service_init(const char *name, enum master_service_flags flags,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen int *argc, char **argv[], const char *getopt_str);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Call getopt() and handle internal parameters. Return values are the same as
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen getopt()'s. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschint master_getopt(struct master_service *service);
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch/* Returns TRUE if str is a valid getopt_str. Currently this only checks for
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen duplicate args so they aren't accidentally added. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschbool master_getopt_str_is_valid(const char *str);
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch/* Parser command line option. Returns TRUE if processed. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschbool master_service_parse_option(struct master_service *service,
c649139f889c02154fc9a153728b81619edb5663Timo Sirainen/* Finish service initialization. The caller should drop privileges
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch before calling this. This also notifies the master that the service was
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch successfully started and there shouldn't be any service throttling even if
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch it crashes afterwards, so this should be called after all of the
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch initialization code is finished. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschvoid master_service_init_finish(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* import_environment is a space-separated list of environment keys or
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen key=values. The key=values are immediately added to the environment.
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch All the keys are added to DOVECOT_PRESERVE_ENVS environment so they're
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch preserved by master_service_env_clean(). */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschvoid master_service_import_environment(const char *import_environment);
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch/* Clean environment from everything except the ones listed in
53ec1ff2231d477db3103c51987fa9cb6033bc16Timo Sirainen DOVECOT_PRESERVE_ENVS environment. */
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen/* Initialize logging. Only the first call changes the actual logging
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen functions. The following calls change the log prefix. */
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainenvoid master_service_init_log(struct master_service *service,
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen const char *prefix);
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen/* If set, die immediately when connection to master is lost.
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainen Normally all existing clients are handled first. */
c215ca02d468b0e542523df1ed18e5f2d7e63968Timo Sirainenvoid master_service_set_die_with_master(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Call the given when master connection dies and die_with_master is TRUE.
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen The callback is expected to shut down the service somewhat soon or it's
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen done forcibly. If NULL, the service is stopped immediately. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_set_die_callback(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen void (*callback)(void));
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* "idle callback" is called when master thinks we're idling and asks us to
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch die. We'll do it only if the idle callback returns TRUE. This callback isn't
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch even called if the master service code knows that we're handling clients. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_set_idle_die_callback(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen bool (*callback)(void));
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Call the given callback when there are no available connections and master
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen has indicated that it can't create any more processes to handle requests.
dafbec2c6b4275233a78cb137f41dd8041aa1c46Timo Sirainen The callback could decide to kill one of the existing connections. */
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Boschvoid master_service_set_avail_overflow_callback(struct master_service *service,
2d7df7973f80011033e8e9fa676d3ff4c14468d8Stephan Bosch void (*callback)(void));
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Set maximum number of clients we can handle. Default is given by master. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_set_client_limit(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns the maximum number of clients we can handle. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_client_limit(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns how many processes of this type can be created before reaching the
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_process_limit(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns service { process_min_avail } */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_process_min_avail(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns the service's idle_kill timeout in seconds. Normally master handles
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen sending the kill request when the process has no clients, but some services
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen with permanent client connections may need to handle this themselves. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_idle_kill_secs(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Set maximum number of client connections we will handle before shutting
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_set_service_count(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen unsigned int count);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns the number of client connections we will handle before shutting
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen down. The value is decreased only after connection has been closed. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_service_count(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Return the number of listener sockets. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenunsigned int master_service_get_socket_count(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns the name of the listener socket, or "" if none is specified. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenconst char *master_service_get_socket_name(struct master_service *service,
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns configuration file path. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenconst char *master_service_get_config_path(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns PACKAGE_VERSION or NULL if version_ignore=yes. This function is
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen useful mostly as parameter to module_dir_load(). */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenconst char *master_service_get_version_string(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns name of the service, as given in name parameter to _init(). */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenconst char *master_service_get_name(struct master_service *service);
a0c453a8edaec90fb0d945c874de0b1845bc7d7eTimo Sirainen/* Start the service. Blocks until finished */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_run(struct master_service *service,
a0c453a8edaec90fb0d945c874de0b1845bc7d7eTimo Sirainen master_service_connection_callback_t *callback)
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen/* Stop a running service. */
b8835b8a21c617ceb82ddc5a176243faf36aa8f7Timo Sirainenvoid master_service_stop(struct master_service *service);
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen/* Stop once we're done serving existing new connections, but don't accept
a0c453a8edaec90fb0d945c874de0b1845bc7d7eTimo Sirainen any new ones. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_stop_new_connections(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns TRUE if we've received a SIGINT/SIGTERM and we've decided to stop. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenbool master_service_is_killed(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns TRUE if our master process is already stopped. This process may or
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen may not be dying itself. Returns FALSE always if the process was started
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen standalone. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenbool master_service_is_master_stopped(struct master_service *service);
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen/* Send command to anvil process, if we have fd to it. */
b8835b8a21c617ceb82ddc5a176243faf36aa8f7Timo Sirainenvoid master_service_anvil_send(struct master_service *service, const char *cmd);
b8835b8a21c617ceb82ddc5a176243faf36aa8f7Timo Sirainen/* Call to accept the client connection. Otherwise the connection is closed. */
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainenvoid master_service_client_connection_accept(struct master_service_connection *conn);
ecdce39e5ef4b62eefa9f5818f17d153fd5d710aTimo Sirainen/* Used to create "extra client connections" outside the common accept()
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_client_connection_created(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Call whenever a client connection is destroyed. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_client_connection_destroyed(struct master_service *service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Deinitialize the service. */
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainenvoid master_service_deinit(struct master_service **service);
48566ca412a7cf3b42512fd0ec112744778e5da0Timo Sirainen/* Returns TRUE if line contains compatible service name and major version.
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen The line is expected to be in format:
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen VERSION <tab> service_name <tab> major version <tab> minor version */
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainenbool version_string_verify(const char *line, const char *service_name,
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen/* Same as version_string_verify(), but return the minor version. */
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainenbool version_string_verify_full(const char *line, const char *service_name,
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen unsigned int *minor_version_r);
8d587838c414c48a331f0b54cd7ffd97e5024abdTimo Sirainen/* Returns TRUE if ssl module has been loaded */