master-service.h revision 0dffa25d211be541ee3c953b23566a1a990789df
ea5f188fc29dfaa0c4071e6413e16e1d04263722Timo Sirainen#include <unistd.h> /* for getopt() opt* variables */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen#include <stdio.h> /* for getopt() opt* variables in Solaris */
f1901fd21906911f7be075c965ac882f6a87b4c3Timo Sirainen /* stdin/stdout already contains a client which we want to serve */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen /* this process is currently running standalone without a master */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen /* Log to configured log file instead of stderr. By default when
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen _FLAG_STANDALONE is set, logging is done to stderr. */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen MASTER_SERVICE_FLAG_DONT_LOG_TO_STDERR = 0x04,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen /* Service is going to do multiple configuration lookups,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen keep the connection to config service open. Also opens the config
d22301419109ed4a38351715e6760011421dadecTimo Sirainen socket before dropping privileges. */
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen /* Don't read settings, but use whatever is in environment */
d22301419109ed4a38351715e6760011421dadecTimo Sirainen MASTER_SERVICE_FLAG_NO_CONFIG_SETTINGS = 0x10,
d22301419109ed4a38351715e6760011421dadecTimo Sirainen /* Use MASTER_LOGIN_NOTIFY_FD to track login overflow state */
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen /* If master sends SIGINT, don't die even if we don't have clients */
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen /* Show number of connections in process title
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen (only if verbose_proctitle setting is enabled) */
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen /* SSL settings are always looked up when we have ssl listeners.
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen This flag enables looking up SSL settings even without ssl
a0b0d629931773c17a236f6214adbe0e13b9b3fdTimo Sirainen listeners (i.e. the service does STARTTLS). */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen /* Don't initialize SSL context automatically. */
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainenmaster_service_connection_callback_t(struct master_service_connection *conn);
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenconst char *master_service_getopt_string(void);
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen/* Start service initialization. */
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainenmaster_service_init(const char *name, enum master_service_flags flags,
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen int *argc, char **argv[], const char *getopt_str);
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen/* Call getopt() and handle internal parameters. Return values are the same as
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen getopt()'s. */
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenint master_getopt(struct master_service *service);
d22301419109ed4a38351715e6760011421dadecTimo Sirainen/* Returns TRUE if str is a valid getopt_str. Currently this only checks for
d22301419109ed4a38351715e6760011421dadecTimo Sirainen duplicate args so they aren't accidentally added. */
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenbool master_getopt_str_is_valid(const char *str);
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen/* Parser command line option. Returns TRUE if processed. */
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenbool master_service_parse_option(struct master_service *service,
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen/* Finish service initialization. The caller should drop privileges
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen before calling this. This also notifies the master that the service was
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen successfully started and there shouldn't be any service throttling even if
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen it crashes afterwards, so this should be called after all of the
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainen initialization code is finished. */
73247459cf41eb1e5ae5bc61354db46d3b05ee75Timo Sirainenvoid master_service_init_finish(struct master_service *service);
d30da25fb6be1f1c667d93767c9194000194b618Timo Sirainen/* Clean environment from everything except the ones listed in
d30da25fb6be1f1c667d93767c9194000194b618Timo Sirainen DOVECOT_PRESERVE_ENVS environment. */
63a61b7a739ae0f3f520215137d9c50f94d0f34fTimo Sirainen/* Initialize logging. */
cd83124e5d070a016c590bb0b1096d7828c7b6adTimo Sirainenvoid master_service_init_log(struct master_service *service,
d22301419109ed4a38351715e6760011421dadecTimo Sirainen const char *prefix);
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen/* If set, die immediately when connection to master is lost.
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen Normally all existing clients are handled first. */
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenvoid master_service_set_die_with_master(struct master_service *service,
4b41116563110d00330896a568eff1078c382827Timo Sirainen/* Call the given when master connection dies and die_with_master is TRUE.
d22301419109ed4a38351715e6760011421dadecTimo Sirainen The callback is expected to shut down the service somewhat soon or it's
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen done forcibly. If NULL, the service is stopped immediately. */
f1901fd21906911f7be075c965ac882f6a87b4c3Timo Sirainenvoid master_service_set_die_callback(struct master_service *service,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen void (*callback)(void));
f1901fd21906911f7be075c965ac882f6a87b4c3Timo Sirainen/* "idle callback" is called when master thinks we're idling and asks us to
6060b7c8edf8fce73470d0df6a2479b69b01c537Timo Sirainen die. We'll do it only if the idle callback returns TRUE. This callback isn't
7f773564b94e6054a40d3785cb63c29f1e4d4deeTimo Sirainen even called if the master service code knows that we're handling clients. */
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainenvoid master_service_set_idle_die_callback(struct master_service *service,
ccc895c0358108d2304239063e940b7d75f364abTimo Sirainen bool (*callback)(void));
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen/* Call the given callback when there are no available connections and master
ca98892a6b8a30ffc1fe26fcf02c7d59e3204e7eTimo Sirainen has indicated that it can't create any more processes to handle requests.
fe6c1556d3529a6376d4cbb3766c34aebde0de99Timo Sirainen The callback could decide to kill one of the existing connections. */
4b41116563110d00330896a568eff1078c382827Timo Sirainenvoid master_service_set_avail_overflow_callback(struct master_service *service,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen void (*callback)(void));
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen/* Set maximum number of clients we can handle. Default is given by master. */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainenvoid master_service_set_client_limit(struct master_service *service,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen/* Returns the maximum number of clients we can handle. */
d22301419109ed4a38351715e6760011421dadecTimo Sirainenunsigned int master_service_get_client_limit(struct master_service *service);
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen/* Returns how many processes of this type can be created before reaching the
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainenunsigned int master_service_get_process_limit(struct master_service *service);
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen/* Returns service { process_min_avail } */
4b41116563110d00330896a568eff1078c382827Timo Sirainenunsigned int master_service_get_process_min_avail(struct master_service *service);
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen/* Returns the service's idle_kill timeout in seconds. Normally master handles
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen sending the kill request when the process has no clients, but some services
b5e6f6f27c1461f0f9f202615eeb738a645188c3Timo Sirainen with permanent client connections may need to handle this themselves. */
345212e8f61ebf14ff4f80df26df9e655eb5121eTimo Sirainenunsigned int master_service_get_idle_kill_secs(struct master_service *service);
345212e8f61ebf14ff4f80df26df9e655eb5121eTimo Sirainen/* Set maximum number of client connections we will handle before shutting
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainenvoid master_service_set_service_count(struct master_service *service,
345212e8f61ebf14ff4f80df26df9e655eb5121eTimo Sirainen unsigned int count);
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen/* Returns the number of client connections we will handle before shutting
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen down. The value is decreased only after connection has been closed. */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainenunsigned int master_service_get_service_count(struct master_service *service);
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen/* Return the number of listener sockets. */
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainenunsigned int master_service_get_socket_count(struct master_service *service);
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen/* Returns the name of the listener socket, or "" if none is specified. */
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainenconst char *master_service_get_socket_name(struct master_service *service,
ae1b268ffff743ad9927c304a1344c5cbd7f909dTimo Sirainen/* Returns configuration file path. */
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainenconst char *master_service_get_config_path(struct master_service *service);
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen/* Returns PACKAGE_VERSION or NULL if version_ignore=yes. This function is
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen useful mostly as parameter to module_dir_load(). */
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainenconst char *master_service_get_version_string(struct master_service *service);
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen/* Returns name of the service, as given in name parameter to _init(). */
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainenconst char *master_service_get_name(struct master_service *service);
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen/* Start the service. Blocks until finished */
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainenvoid master_service_run(struct master_service *service,
90adcaa0a00eba29b7fbd50ca66be11c8d086d6aTimo Sirainen master_service_connection_callback_t *callback)
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen/* Stop a running service. */
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainenvoid master_service_stop(struct master_service *service);
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen/* Stop once we're done serving existing new connections, but don't accept
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen any new ones. */
d22301419109ed4a38351715e6760011421dadecTimo Sirainenvoid master_service_stop_new_connections(struct master_service *service);
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen/* Returns TRUE if we've received a SIGINT/SIGTERM and we've decided to stop. */
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainenbool master_service_is_killed(struct master_service *service);
e6aa82aeb50948cb47a45a1b61a9c16d6a162388Timo Sirainen/* Returns TRUE if our master process is already stopped. This process may or
e6aa82aeb50948cb47a45a1b61a9c16d6a162388Timo Sirainen may not be dying itself. Returns FALSE always if the process was started
e6aa82aeb50948cb47a45a1b61a9c16d6a162388Timo Sirainen standalone. */
e6aa82aeb50948cb47a45a1b61a9c16d6a162388Timo Sirainenbool master_service_is_master_stopped(struct master_service *service);
cd83124e5d070a016c590bb0b1096d7828c7b6adTimo Sirainen/* Send command to anvil process, if we have fd to it. */
cd83124e5d070a016c590bb0b1096d7828c7b6adTimo Sirainenvoid master_service_anvil_send(struct master_service *service, const char *cmd);
cd83124e5d070a016c590bb0b1096d7828c7b6adTimo Sirainen/* Call to accept the client connection. Otherwise the connection is closed. */
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainenvoid master_service_client_connection_accept(struct master_service_connection *conn);
bf9402875418faf11825cf11fbe06326b6086e3dTimo Sirainen/* Used to create "extra client connections" outside the common accept()
bf9402875418faf11825cf11fbe06326b6086e3dTimo Sirainenvoid master_service_client_connection_created(struct master_service *service);
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen/* Call whenever a client connection is destroyed. */
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainenvoid master_service_client_connection_destroyed(struct master_service *service);
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainen/* Deinitialize the service. */
5daa12cc1c862eec4f63df42227812d3514da2ccTimo Sirainenvoid master_service_deinit(struct master_service **service);
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen/* Returns TRUE if line contains compatible service name and major version.
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen The line is expected to be in format:
83bb013a99f0936995f9c7a1077822662d8fefdbTimo Sirainen VERSION <tab> service_name <tab> major version <tab> minor version */
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainenbool version_string_verify(const char *line, const char *service_name,
d22301419109ed4a38351715e6760011421dadecTimo Sirainen/* Same as version_string_verify(), but return the minor version. */
f140f88a5ab3e2194f214c11f9f418559e949c83Timo Sirainenbool version_string_verify_full(const char *line, const char *service_name,
8fcff4c5b52f24d9c681805fdf06b486f1d0fcbeTimo Sirainen unsigned int *minor_version_r);