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