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