src/core/unit.h

   1 /*-*- Mode: C; c-basic-offset: 8; indent-tabs-mode: nil -*-*/
   2
   3 #pragma once
   4
   5 /***
   6   This file is part of systemd.
   7
   8   Copyright 2010 Lennart Poettering
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 ***/
  23
  24 #include <stdbool.h>
  25 #include <stdlib.h>
  26 #include <unistd.h>
  27
  28 typedef struct Unit Unit;
  29 typedef struct UnitVTable UnitVTable;
  30 typedef enum UnitActiveState UnitActiveState;
  31 typedef enum UnitDependency UnitDependency;
  32 typedef struct UnitRef UnitRef;
  33 typedef struct UnitStatusMessageFormats UnitStatusMessageFormats;
  34
  35 #include "set.h"
  36 #include "util.h"
  37 #include "list.h"
  38 #include "socket-util.h"
  39 #include "execute.h"
  40 #include "condition.h"
  41 #include "install.h"
  42 #include "unit-name.h"
  43 #include "cgroup-semantics.h"
  44
  45 enum UnitActiveState {
  46         UNIT_ACTIVE,
  47         UNIT_RELOADING,
  48         UNIT_INACTIVE,
  49         UNIT_FAILED,
  50         UNIT_ACTIVATING,
  51         UNIT_DEACTIVATING,
  52         _UNIT_ACTIVE_STATE_MAX,
  53         _UNIT_ACTIVE_STATE_INVALID = -1
  54 };
  55
  56 static inline bool UNIT_IS_ACTIVE_OR_RELOADING(UnitActiveState t) {
  57         return t == UNIT_ACTIVE || t == UNIT_RELOADING;
  58 }
  59
  60 static inline bool UNIT_IS_ACTIVE_OR_ACTIVATING(UnitActiveState t) {
  61         return t == UNIT_ACTIVE || t == UNIT_ACTIVATING || t == UNIT_RELOADING;
  62 }
  63
  64 static inline bool UNIT_IS_INACTIVE_OR_DEACTIVATING(UnitActiveState t) {
  65         return t == UNIT_INACTIVE || t == UNIT_FAILED || t == UNIT_DEACTIVATING;
  66 }
  67
  68 static inline bool UNIT_IS_INACTIVE_OR_FAILED(UnitActiveState t) {
  69         return t == UNIT_INACTIVE || t == UNIT_FAILED;
  70 }
  71
  72 enum UnitDependency {
  73         /* Positive dependencies */
  74         UNIT_REQUIRES,
  75         UNIT_REQUIRES_OVERRIDABLE,
  76         UNIT_REQUISITE,
  77         UNIT_REQUISITE_OVERRIDABLE,
  78         UNIT_WANTS,
  79         UNIT_BINDS_TO,
  80         UNIT_PART_OF,
  81
  82         /* Inverse of the above */
  83         UNIT_REQUIRED_BY,             /* inverse of 'requires' and 'requisite' is 'required_by' */
  84         UNIT_REQUIRED_BY_OVERRIDABLE, /* inverse of 'requires_overridable' and 'requisite_overridable' is 'soft_required_by' */
  85         UNIT_WANTED_BY,               /* inverse of 'wants' */
  86         UNIT_BOUND_BY,                /* inverse of 'binds_to' */
  87         UNIT_CONSISTS_OF,             /* inverse of 'part_of' */
  88
  89         /* Negative dependencies */
  90         UNIT_CONFLICTS,               /* inverse of 'conflicts' is 'conflicted_by' */
  91         UNIT_CONFLICTED_BY,
  92
  93         /* Order */
  94         UNIT_BEFORE,                  /* inverse of 'before' is 'after' and vice versa */
  95         UNIT_AFTER,
  96
  97         /* On Failure */
  98         UNIT_ON_FAILURE,
  99
 100         /* Triggers (i.e. a socket triggers a service) */
 101         UNIT_TRIGGERS,
 102         UNIT_TRIGGERED_BY,
 103
 104         /* Propagate reloads */
 105         UNIT_PROPAGATES_RELOAD_TO,
 106         UNIT_RELOAD_PROPAGATED_FROM,
 107
 108         /* Reference information for GC logic */
 109         UNIT_REFERENCES,              /* Inverse of 'references' is 'referenced_by' */
 110         UNIT_REFERENCED_BY,
 111
 112         _UNIT_DEPENDENCY_MAX,
 113         _UNIT_DEPENDENCY_INVALID = -1
 114 };
 115
 116 #include "manager.h"
 117 #include "job.h"
 118 #include "cgroup.h"
 119 #include "cgroup-attr.h"
 120
 121 struct UnitRef {
 122         /* Keeps tracks of references to a unit. This is useful so
 123          * that we can merge two units if necessary and correct all
 124          * references to them */
 125
 126         Unit* unit;
 127         LIST_FIELDS(UnitRef, refs);
 128 };
 129
 130 struct Unit {
 131         Manager *manager;
 132
 133         UnitType type;
 134         UnitLoadState load_state;
 135         Unit *merged_into;
 136
 137         char *id; /* One name is special because we use it for identification. Points to an entry in the names set */
 138         char *instance;
 139
 140         Set *names;
 141         Set *dependencies[_UNIT_DEPENDENCY_MAX];
 142
 143         char **requires_mounts_for;
 144
 145         char *description;
 146         char **documentation;
 147
 148         char *fragment_path; /* if loaded from a config file this is the primary path to it */
 149         char *source_path; /* if converted, the source file */
 150         char **dropin_paths;
 151         usec_t fragment_mtime;
 152         usec_t source_mtime;
 153         usec_t dropin_mtime;
 154
 155         /* If there is something to do with this unit, then this is the installed job for it */
 156         Job *job;
 157
 158         /* JOB_NOP jobs are special and can be installed without disturbing the real job. */
 159         Job *nop_job;
 160
 161         usec_t job_timeout;
 162
 163         /* References to this */
 164         LIST_HEAD(UnitRef, refs);
 165
 166         /* Conditions to check */
 167         LIST_HEAD(Condition, conditions);
 168
 169         dual_timestamp condition_timestamp;
 170
 171         dual_timestamp inactive_exit_timestamp;
 172         dual_timestamp active_enter_timestamp;
 173         dual_timestamp active_exit_timestamp;
 174         dual_timestamp inactive_enter_timestamp;
 175
 176         /* Counterparts in the cgroup filesystem */
 177         CGroupBonding *cgroup_bondings;
 178         CGroupAttribute *cgroup_attributes;
 179
 180         UnitRef slice;
 181
 182         /* Per type list */
 183         LIST_FIELDS(Unit, units_by_type);
 184
 185         /* All units which have requires_mounts_for set */
 186         LIST_FIELDS(Unit, has_requires_mounts_for);
 187
 188         /* Load queue */
 189         LIST_FIELDS(Unit, load_queue);
 190
 191         /* D-Bus queue */
 192         LIST_FIELDS(Unit, dbus_queue);
 193
 194         /* Cleanup queue */
 195         LIST_FIELDS(Unit, cleanup_queue);
 196
 197         /* GC queue */
 198         LIST_FIELDS(Unit, gc_queue);
 199
 200         /* Used during GC sweeps */
 201         unsigned gc_marker;
 202
 203         /* When deserializing, temporarily store the job type for this
 204          * unit here, if there was a job scheduled.
 205          * Only for deserializing from a legacy version. New style uses full
 206          * serialized jobs. */
 207         int deserialized_job; /* This is actually of type JobType */
 208
 209         /* Error code when we didn't manage to load the unit (negative) */
 210         int load_error;
 211
 212         /* Cached unit file state */
 213         UnitFileState unit_file_state;
 214
 215         /* Garbage collect us we nobody wants or requires us anymore */
 216         bool stop_when_unneeded;
 217
 218         /* Create default dependencies */
 219         bool default_dependencies;
 220
 221         /* Refuse manual starting, allow starting only indirectly via dependency. */
 222         bool refuse_manual_start;
 223
 224         /* Don't allow the user to stop this unit manually, allow stopping only indirectly via dependency. */
 225         bool refuse_manual_stop;
 226
 227         /* Allow isolation requests */
 228         bool allow_isolate;
 229
 230         /* Isolate OnFailure unit */
 231         bool on_failure_isolate;
 232
 233         /* Ignore this unit when isolating */
 234         bool ignore_on_isolate;
 235
 236         /* Ignore this unit when snapshotting */
 237         bool ignore_on_snapshot;
 238
 239         /* Did the last condition check succeed? */
 240         bool condition_result;
 241
 242         bool in_load_queue:1;
 243         bool in_dbus_queue:1;
 244         bool in_cleanup_queue:1;
 245         bool in_gc_queue:1;
 246
 247         bool sent_dbus_new_signal:1;
 248
 249         bool no_gc:1;
 250
 251         bool in_audit:1;
 252 };
 253
 254 struct UnitStatusMessageFormats {
 255         const char *starting_stopping[2];
 256         const char *finished_start_job[_JOB_RESULT_MAX];
 257         const char *finished_stop_job[_JOB_RESULT_MAX];
 258 };
 259
 260 #include "service.h"
 261 #include "timer.h"
 262 #include "socket.h"
 263 #include "target.h"
 264 #include "device.h"
 265 #include "mount.h"
 266 #include "automount.h"
 267 #include "snapshot.h"
 268 #include "swap.h"
 269 #include "path.h"
 270 #include "slice.h"
 271
 272 struct UnitVTable {
 273         /* How much memory does an object of this unit type need */
 274         size_t object_size;
 275
 276         /* If greater than 0, the offset into the object where
 277          * ExecContext is found, if the unit type has that */
 278         size_t exec_context_offset;
 279
 280         /* The name of the section with the exec settings of ExecContext */
 281         const char *exec_section;
 282
 283         /* Config file sections this unit type understands, separated
 284          * by NUL chars */
 285         const char *sections;
 286
 287         /* This should reset all type-specific variables. This should
 288          * not allocate memory, and is called with zero-initialized
 289          * data. It should hence only initialize variables that need
 290          * to be set != 0. */
 291         void (*init)(Unit *u);
 292
 293         /* This should free all type-specific variables. It should be
 294          * idempotent. */
 295         void (*done)(Unit *u);
 296
 297         /* Actually load data from disk. This may fail, and should set
 298          * load_state to UNIT_LOADED, UNIT_MERGED or leave it at
 299          * UNIT_STUB if no configuration could be found. */
 300         int (*load)(Unit *u);
 301
 302         /* If a lot of units got created via enumerate(), this is
 303          * where to actually set the state and call unit_notify(). */
 304         int (*coldplug)(Unit *u);
 305
 306         void (*dump)(Unit *u, FILE *f, const char *prefix);
 307
 308         int (*start)(Unit *u);
 309         int (*stop)(Unit *u);
 310         int (*reload)(Unit *u);
 311
 312         int (*kill)(Unit *u, KillWho w, int signo, DBusError *error);
 313
 314         bool (*can_reload)(Unit *u);
 315
 316         /* Write all data that cannot be restored from other sources
 317          * away using unit_serialize_item() */
 318         int (*serialize)(Unit *u, FILE *f, FDSet *fds);
 319
 320         /* Restore one item from the serialization */
 321         int (*deserialize_item)(Unit *u, const char *key, const char *data, FDSet *fds);
 322
 323         /* Try to match up fds with what we need for this unit */
 324         int (*distribute_fds)(Unit *u, FDSet *fds);
 325
 326         /* Boils down the more complex internal state of this unit to
 327          * a simpler one that the engine can understand */
 328         UnitActiveState (*active_state)(Unit *u);
 329
 330         /* Returns the substate specific to this unit type as
 331          * string. This is purely information so that we can give the
 332          * user a more fine grained explanation in which actual state a
 333          * unit is in. */
 334         const char* (*sub_state_to_string)(Unit *u);
 335
 336         /* Return true when there is reason to keep this entry around
 337          * even nothing references it and it isn't active in any
 338          * way */
 339         bool (*check_gc)(Unit *u);
 340
 341         /* Return true when this unit is suitable for snapshotting */
 342         bool (*check_snapshot)(Unit *u);
 343
 344         void (*fd_event)(Unit *u, int fd, uint32_t events, Watch *w);
 345         void (*sigchld_event)(Unit *u, pid_t pid, int code, int status);
 346         void (*timer_event)(Unit *u, uint64_t n_elapsed, Watch *w);
 347
 348         /* Reset failed state if we are in failed state */
 349         void (*reset_failed)(Unit *u);
 350
 351         /* Called whenever any of the cgroups this unit watches for
 352          * ran empty */
 353         void (*cgroup_notify_empty)(Unit *u);
 354
 355         /* Called whenever a process of this unit sends us a message */
 356         void (*notify_message)(Unit *u, pid_t pid, char **tags);
 357
 358         /* Called whenever a name this Unit registered for comes or
 359          * goes away. */
 360         void (*bus_name_owner_change)(Unit *u, const char *name, const char *old_owner, const char *new_owner);
 361
 362         /* Called whenever a bus PID lookup finishes */
 363         void (*bus_query_pid_done)(Unit *u, const char *name, pid_t pid);
 364
 365         /* Called for each message received on the bus */
 366         DBusHandlerResult (*bus_message_handler)(Unit *u, DBusConnection *c, DBusMessage *message);
 367
 368         /* Return the unit this unit is following */
 369         Unit *(*following)(Unit *u);
 370
 371         /* Return the set of units that are following each other */
 372         int (*following_set)(Unit *u, Set **s);
 373
 374         /* Invoked each time a unit this unit is triggering changes
 375          * state or gains/loses a job */
 376         void (*trigger_notify)(Unit *u, Unit *trigger);
 377
 378         /* Called whenever CLOCK_REALTIME made a jump */
 379         void (*time_change)(Unit *u);
 380
 381         /* This is called for each unit type and should be used to
 382          * enumerate existing devices and load them. However,
 383          * everything that is loaded here should still stay in
 384          * inactive state. It is the job of the coldplug() call above
 385          * to put the units into the initial state.  */
 386         int (*enumerate)(Manager *m);
 387
 388         /* Type specific cleanups. */
 389         void (*shutdown)(Manager *m);
 390
 391         /* When sending out PropertiesChanged signal, which properties
 392          * shall be invalidated? This is a NUL separated list of
 393          * strings, to minimize relocations a little. */
 394         const char *bus_invalidating_properties;
 395
 396         /* The interface name */
 397         const char *bus_interface;
 398
 399         UnitStatusMessageFormats status_message_formats;
 400
 401         /* Can units of this type have multiple names? */
 402         bool no_alias:1;
 403
 404         /* Instances make no sense for this type */
 405         bool no_instances:1;
 406
 407         /* Exclude from automatic gc */
 408         bool no_gc:1;
 409 };
 410
 411 extern const UnitVTable * const unit_vtable[_UNIT_TYPE_MAX];
 412
 413 #define UNIT_VTABLE(u) unit_vtable[(u)->type]
 414
 415 /* For casting a unit into the various unit types */
 416 #define DEFINE_CAST(UPPERCASE, MixedCase)                               \
 417         static inline MixedCase* UPPERCASE(Unit *u) {                   \
 418                 if (_unlikely_(!u || u->type != UNIT_##UPPERCASE))      \
 419                         return NULL;                                    \
 420                                                                         \
 421                 return (MixedCase*) u;                                  \
 422         }
 423
 424 /* For casting the various unit types into a unit */
 425 #define UNIT(u) (&(u)->meta)
 426
 427 #define UNIT_TRIGGER(u) ((Unit*) set_first((u)->dependencies[UNIT_TRIGGERS]))
 428
 429 DEFINE_CAST(SOCKET, Socket);
 430 DEFINE_CAST(TIMER, Timer);
 431 DEFINE_CAST(SERVICE, Service);
 432 DEFINE_CAST(TARGET, Target);
 433 DEFINE_CAST(DEVICE, Device);
 434 DEFINE_CAST(MOUNT, Mount);
 435 DEFINE_CAST(AUTOMOUNT, Automount);
 436 DEFINE_CAST(SNAPSHOT, Snapshot);
 437 DEFINE_CAST(SWAP, Swap);
 438 DEFINE_CAST(PATH, Path);
 439 DEFINE_CAST(SLICE, Slice);
 440
 441 Unit *unit_new(Manager *m, size_t size);
 442 void unit_free(Unit *u);
 443
 444 int unit_add_name(Unit *u, const char *name);
 445
 446 int unit_add_dependency(Unit *u, UnitDependency d, Unit *other, bool add_reference);
 447 int unit_add_two_dependencies(Unit *u, UnitDependency d, UnitDependency e, Unit *other, bool add_reference);
 448
 449 int unit_add_dependency_by_name(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
 450 int unit_add_two_dependencies_by_name(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
 451
 452 int unit_add_dependency_by_name_inverse(Unit *u, UnitDependency d, const char *name, const char *filename, bool add_reference);
 453 int unit_add_two_dependencies_by_name_inverse(Unit *u, UnitDependency d, UnitDependency e, const char *name, const char *path, bool add_reference);
 454
 455 int unit_add_exec_dependencies(Unit *u, ExecContext *c);
 456
 457 int unit_add_cgroup_from_text(Unit *u, const char *name, bool overwrite, CGroupBonding **ret);
 458 int unit_add_default_cgroups(Unit *u);
 459 CGroupBonding* unit_get_default_cgroup(Unit *u);
 460 int unit_add_cgroup_attribute(Unit *u, const CGroupSemantics *semantics, const char *controller, const char *name, const char *value, CGroupAttribute **ret);
 461
 462 int unit_choose_id(Unit *u, const char *name);
 463 int unit_set_description(Unit *u, const char *description);
 464
 465 bool unit_check_gc(Unit *u);
 466
 467 void unit_add_to_load_queue(Unit *u);
 468 void unit_add_to_dbus_queue(Unit *u);
 469 void unit_add_to_cleanup_queue(Unit *u);
 470 void unit_add_to_gc_queue(Unit *u);
 471
 472 int unit_merge(Unit *u, Unit *other);
 473 int unit_merge_by_name(Unit *u, const char *other);
 474
 475 Unit *unit_follow_merge(Unit *u) _pure_;
 476
 477 int unit_load_fragment_and_dropin(Unit *u);
 478 int unit_load_fragment_and_dropin_optional(Unit *u);
 479 int unit_load(Unit *unit);
 480
 481 int unit_add_default_slice(Unit *u);
 482
 483 const char *unit_description(Unit *u) _pure_;
 484
 485 bool unit_has_name(Unit *u, const char *name);
 486
 487 UnitActiveState unit_active_state(Unit *u);
 488
 489 const char* unit_sub_state_to_string(Unit *u);
 490
 491 void unit_dump(Unit *u, FILE *f, const char *prefix);
 492
 493 bool unit_can_reload(Unit *u) _pure_;
 494 bool unit_can_start(Unit *u) _pure_;
 495 bool unit_can_isolate(Unit *u) _pure_;
 496
 497 int unit_start(Unit *u);
 498 int unit_stop(Unit *u);
 499 int unit_reload(Unit *u);
 500
 501 int unit_kill(Unit *u, KillWho w, int signo, DBusError *error);
 502 int unit_kill_common(Unit *u, KillWho who, int signo, pid_t main_pid, pid_t control_pid, DBusError *error);
 503
 504 void unit_notify(Unit *u, UnitActiveState os, UnitActiveState ns, bool reload_success);
 505
 506 int unit_watch_fd(Unit *u, int fd, uint32_t events, Watch *w);
 507 void unit_unwatch_fd(Unit *u, Watch *w);
 508
 509 int unit_watch_pid(Unit *u, pid_t pid);
 510 void unit_unwatch_pid(Unit *u, pid_t pid);
 511
 512 int unit_watch_timer(Unit *u, clockid_t, bool relative, usec_t usec, Watch *w);
 513 void unit_unwatch_timer(Unit *u, Watch *w);
 514
 515 int unit_watch_bus_name(Unit *u, const char *name);
 516 void unit_unwatch_bus_name(Unit *u, const char *name);
 517
 518 bool unit_job_is_applicable(Unit *u, JobType j);
 519
 520 int set_unit_path(const char *p);
 521
 522 char *unit_dbus_path(Unit *u);
 523
 524 int unit_load_related_unit(Unit *u, const char *type, Unit **_found);
 525 int unit_get_related_unit(Unit *u, const char *type, Unit **_found);
 526
 527 bool unit_can_serialize(Unit *u) _pure_;
 528 int unit_serialize(Unit *u, FILE *f, FDSet *fds, bool serialize_jobs);
 529 void unit_serialize_item_format(Unit *u, FILE *f, const char *key, const char *value, ...) _printf_attr_(4,5);
 530 void unit_serialize_item(Unit *u, FILE *f, const char *key, const char *value);
 531 int unit_deserialize(Unit *u, FILE *f, FDSet *fds);
 532
 533 int unit_add_node_link(Unit *u, const char *what, bool wants);
 534
 535 int unit_coldplug(Unit *u);
 536
 537 void unit_status_printf(Unit *u, const char *status, const char *unit_status_msg_format) _printf_attr_(3, 0);
 538
 539 bool unit_need_daemon_reload(Unit *u);
 540
 541 void unit_reset_failed(Unit *u);
 542
 543 Unit *unit_following(Unit *u);
 544
 545 bool unit_stop_pending(Unit *u) _pure_;
 546 bool unit_inactive_or_pending(Unit *u) _pure_;
 547 bool unit_active_or_pending(Unit *u);
 548
 549 int unit_add_default_target_dependency(Unit *u, Unit *target);
 550
 551 char *unit_default_cgroup_path(Unit *u);
 552
 553 int unit_following_set(Unit *u, Set **s);
 554
 555 void unit_start_on_failure(Unit *u);
 556 void unit_trigger_notify(Unit *u);
 557
 558 bool unit_condition_test(Unit *u);
 559
 560 UnitFileState unit_get_unit_file_state(Unit *u);
 561
 562 Unit* unit_ref_set(UnitRef *ref, Unit *u);
 563 void unit_ref_unset(UnitRef *ref);
 564
 565 #define UNIT_DEREF(ref) ((ref).unit)
 566
 567 int unit_add_one_mount_link(Unit *u, Mount *m);
 568 int unit_add_mount_links(Unit *u);
 569
 570 int unit_exec_context_defaults(Unit *u, ExecContext *c);
 571
 572 ExecContext *unit_get_exec_context(Unit *u) _pure_;
 573
 574 int unit_write_drop_in(Unit *u, bool runtime, const char *name, const char *data);
 575 int unit_remove_drop_in(Unit *u, bool runtime, const char *name);
 576
 577 int unit_kill_context(Unit *u, KillContext *c, bool sigkill, pid_t main_pid, pid_t control_pid, bool main_pid_alien);
 578
 579 const char *unit_active_state_to_string(UnitActiveState i) _const_;
 580 UnitActiveState unit_active_state_from_string(const char *s) _pure_;
 581
 582 const char *unit_dependency_to_string(UnitDependency i) _const_;
 583 UnitDependency unit_dependency_from_string(const char *s) _pure_;
 584
 585 /* Macros which append UNIT= or USER_UNIT= to the message */
 586
 587 #define log_full_unit(level, unit, ...) log_meta_object(level, __FILE__, __LINE__, __func__, getpid() == 1 ? "UNIT=" : "USER_UNIT=", unit, __VA_ARGS__)
 588 #define log_debug_unit(unit, ...)       log_full_unit(LOG_DEBUG, unit, __VA_ARGS__)
 589 #define log_info_unit(unit, ...)        log_full_unit(LOG_INFO, unit, __VA_ARGS__)
 590 #define log_notice_unit(unit, ...)      log_full_unit(LOG_NOTICE, unit, __VA_ARGS__)
 591 #define log_warning_unit(unit, ...)     log_full_unit(LOG_WARNING, unit, __VA_ARGS__)
 592 #define log_error_unit(unit, ...)       log_full_unit(LOG_ERR, unit, __VA_ARGS__)
 593
 594 #define log_struct_unit(level, unit, ...) log_struct(level, getpid() == 1 ? "UNIT=%s" : "USER_UNIT=%s", unit, __VA_ARGS__)