diff --git a/.vscode/settings.json b/.vscode/settings.json deleted file mode 100644 index 4009c66d7..000000000 --- a/.vscode/settings.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "go.lintTool":"golangci-lint", - "go.lintFlags": [ - "--fast" - ] -} \ No newline at end of file diff --git a/docs/doc-cheat-sheet.rst b/docs/doc-cheat-sheet.rst deleted file mode 100644 index b12ebcdf7..000000000 --- a/docs/doc-cheat-sheet.rst +++ /dev/null @@ -1,258 +0,0 @@ -:orphan: - -.. _cheat-sheet: - -reStructuredText cheat sheet -============================ - -This file contains the syntax for commonly used reST markup. -Open it in your text editor to quickly copy and paste the markup you need. - -See the `reStructuredText style guide `_ for detailed information and conventions. - -Also see the `Sphinx reStructuredText Primer `_ for more details on reST, and the `Canonical Documentation Style Guide `_ for general style conventions. - -H2 heading ----------- - -H3 heading -~~~~~~~~~~ - -H4 heading -^^^^^^^^^^ - -H5 heading -.......... - -Inline formatting ------------------ - -- :guilabel:`UI element` -- ``code`` -- :file:`file path` -- :command:`command` -- :kbd:`Key` -- *Italic* -- **Bold** - -Code blocks ------------ - -Start a code block:: - - code: - - example: true - -.. code:: - - # Demonstrate a code block - code: - - example: true - -.. code:: yaml - - # Demonstrate a code block - code: - - example: true - -.. _a_section_target: - -Links ------ - -- `Canonical website `_ -- `Canonical website`_ (defined in ``reuse/links.txt`` or at the bottom of the page) -- https:\ //canonical.com/ -- :ref:`a_section_target` -- :ref:`Link text ` -- :doc:`index` -- :doc:`Link text ` - - -Navigation ----------- - -Use the following syntax:: - - .. toctree:: - :hidden: - - sub-page1 - sub-page2 - - -Lists ------ - -1. Step 1 - - - Item 1 - - * Sub-item - - Item 2 - - i. Sub-step 1 - #. Sub-step 2 -#. Step 2 - - a. Sub-step 1 - - - Item - #. Sub-step 2 - -Term 1: - Definition -Term 2: - Definition - -Tables ------- - -+----------------------+------------+ -| Header 1 | Header 2 | -+======================+============+ -| Cell 1 | Cell 2 | -| | | -| Second paragraph | | -+----------------------+------------+ -| Cell 3 | Cell 4 | -+----------------------+------------+ - -.. list-table:: - :header-rows: 1 - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph - - Cell 2 - * - Cell 3 - - Cell 4 - -.. rst-class:: align-center - - +----------------------+------------+ - | Header 1 | Header 2 | - +======================+============+ - | Cell 1 | Cell 2 | - | | | - | Second paragraph | | - +----------------------+------------+ - | Cell 3 | Cell 4 | - +----------------------+------------+ - -.. list-table:: - :header-rows: 1 - :align: center - - * - Header 1 - - Header 2 - * - Cell 1 - - Second paragraph - - Cell 2 - * - Cell 3 - - Cell 4 - -Notes ------ - -.. note:: - A note. - -.. tip:: - A tip. - -.. important:: - Important information - -.. caution:: - This might damage your hardware! - -Images ------- - -.. image:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - -.. figure:: https://assets.ubuntu.com/v1/b3b72cb2-canonical-logo-166.png - :width: 100px - :alt: Alt text - - Figure caption - -Reuse ------ - -.. |reuse_key| replace:: This is **included** text. - -|reuse_key| - -.. include:: index.rst - :start-after: include_start - :end-before: include_end - -Tabs ----- - -.. tabs:: - - .. group-tab:: Tab 1 - - Content Tab 1 - - .. group-tab:: Tab 2 - - Content Tab 2 - - -Glossary --------- - -.. glossary:: - - example term - Definition of the example term. - -:term:`example term` - -More useful markup ------------------- - -- .. versionadded:: X.Y -- | Line 1 - | Line 2 - | Line 3 -- .. This is a comment -- :abbr:`API (Application Programming Interface)` - ----- - -Custom extensions ------------------ - -Related links at the top of the page:: - - :relatedlinks: https://github.com/canonical/lxd-sphinx-extensions, [RTFM](https://www.google.com) - :discourse: 12345 - -Terms that should not be checked by the spelling checker: :spellexception:`PurposelyWrong` - -A terminal view with input and output: - -.. terminal:: - :input: command - :user: root - :host: vampyr - - the output - -A link to a YouTube video: - -.. youtube:: https://www.youtube.com/watch?v=iMLiK1fX4I0 - :title: Demo - - - -.. LINKS -.. _Canonical website: https://canonical.com/ diff --git a/docs/index.md b/docs/index.md index a640097f4..2c059c4b4 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,9 @@ ADSys is valuable for system administrators who wish to manage Ubuntu Desktop cl ```{toctree} :hidden: how-to/index -CLI reference +reference/index + + ``` ## Project and community diff --git a/docs/reference/adsys-daemon.md b/docs/reference/adsys-daemon.md new file mode 100644 index 000000000..fc34cdaf3 --- /dev/null +++ b/docs/reference/adsys-daemon.md @@ -0,0 +1,207 @@ +# The adsys daemon + +## Policy enforcement + +### When are the policies refreshed + +On the client the policies are refreshed in 3 situations: + +* At boot time for the policy of the machine. +* At login time for the policy of the user. +* Periodically by a timer for the machine and the user policy. + +### What happens when a policy refresh fails + +When the client is offline, e.g. a laptop, or the Active Directory server is unreachable, you still want to use the machine and be able to log in. For this purpose, ADSys uses a cache located in `/var/cache/adsys`. + +>There are 2 types of cache: +> +>* A cache for the GPO downloaded from the server in directory `gpo_cache` +>* A cache for the rules as applied by ADSys in `policies` + +The enforcement of the policy will fail when the cache is empty or the client fails to retrieve the policy from the server. + +If the enforcement of the policy fails: + +* At boot time, ADSys stops the boot process. +* At login time, login is denied. +* During periodic refresh, the policy currently applied on the client remains. + +### How to change refresh rate + +Periodic refresh of the policies (machine and active users) is handled by the systemd timer unit `adsys-gpo-refresh.timer`. + +You can list the timers with the command `systemctl list-timers`. + +```sh +$ systemctl list-timers +NEXT LEFT LAST PASSED UNIT ACTIVATES +Tue 2021-05-18 10:05:49 CEST 11min left Tue 2021-05-18 09:35:49 CEST 18min ago adsys-gpo-refresh.timer adsys-gpo-refresh.service +Tue 2021-05-18 10:31:34 CEST 36min left Tue 2021-05-18 09:31:09 CEST 23min ago anacron.timer anacron.service +[...] +``` + +The default refresh rate is **30 minutes**. + +You can override the refresh rate with the configuration variables `OnBootSec` and `OnUnitActiveSec` in a configuration file as follow: + +`/etc/systemd/system/adsys-gpo-refresh.timer.d/refresh-rate.conf`: + +```ini +# Refresh ADSys GPO every 2 hours +[Timer] +OnBootSec= +OnBootSec=120min +OnUnitActiveSec= +OnUnitActiveSec=120min +``` + +The changes will be effective after a reload of the daemon with `systemctl daemon-reload` or after a reboot. + +```sh +$ sudo systemctl daemon-reload +$ sudo systemctl list-timers +NEXT LEFT LAST PASSED UNIT ACTIVATES +Tue 2021-05-18 10:35:45 CEST 16min left Tue 2021-05-18 10:05:50 CEST 1h43min ago adsys-gpo-refresh.timer adsys-gpo-refresh.service +[...] +``` + +> The empty `OnBootSec=` and `OnUnitActiveSec=` statements are used to reset the system-wide timer unit time instead of adding new timers. `man systemd.timer` for more information. + +You can get more details about the timer status itself as an administrator: + +```sh +$ sudo systemctl status adsys-gpo-refresh.timer +● adsys-gpo-refresh.timer - Refresh ADSys GPO for machine and users + Loaded: loaded (/lib/systemd/system/adsys-gpo-refresh.timer; enabled; vendor preset: enabled) + Active: active (waiting) since Tue 2021-05-18 08:35:48 CEST; 1h 23min ago + Trigger: Tue 2021-05-18 10:05:49 CEST; 6min left + Triggers: ● adsys-gpo-refresh.service + +may 18 08:35:48 adclient04 systemd[1]: Started Refresh ADSys GPO for machine and users. +``` + +**TODO: adsysctl service status to get next scheduled refresh** + +## Socket activation + +The ADSys daemon is started on demand by systemd’s socket activation and only runs when it’s required. It will gracefully shutdown after idling for a short period of time (by default 120 seconds). + +## Configuration + +`ADSys` doesn’t ship a configuration file by default. However, such a file can be created to modify the behavior of the daemon and the client. + +The configuration file can be system-wide in `/etc/adsys.yaml`. This will thus apply to both daemon and client. You can have per-user configuration by creating `$HOME/adsys.yaml`. It will then affect only the client for this user. + +The current directory is also searched for an `adsys.yaml` file. + +Finally, each `adsysd` and `adsysctl` commands accept a `--config|-c ` flag to set the path to a configuration file at run time. It can be used for testing purpose for instance. + +An example of configuration file with all the options can be found in the [ADSys repository](https://github.com/ubuntu/adsys/blob/main/conf.example/adsys.yaml): + +```yaml +# Service and client configuration +verbose: 2 +socket: /tmp/adsysd/socket + +# Service only configuration +service_timeout: 3600 +cache_dir: /tmp/adsysd/cache +run_dir: /tmp/adsysd/run + +# Backend selection: sssd (default) or winbind +ad_backend: sssd + +# SSSd configuration +sssd: + config: /etc/sssd.conf + cache_dir: /var/lib/sss/db + +# Winbind configuration +# (if ad_backend is set to winbind) +winbind: + ad_domain: domain.com + ad_server: adc.domain.com + +# Client only configuration +client_timeout: 60 +``` + +### Configuration common between service and client + +* **verbose** +Increase the verbosity of the daemon or client. By default, only warnings and error logs are printed. This value is set between 0 and 3. This has the same effect as the `-v` and `-vv` flags. + +* **socket** +Path the unix socket for communication between clients and daemon. This can be overridden by the `--socket` option. Defaults to `/run/adsysd.sock` (monitored by systemd for socket activation). + +### Service only configuration + +* **service_timeout** +Time in seconds without any active request before the service exits. This can be overridden by the `--timeout` option. Defaults to 120 seconds. + +* **backend** +Backend to use to integrate with Active Directory. It is responsible for providing valid kerberos tickets. Available selection is `sssd` or `winbind`. Default is `sssd`. This can be overridden by the `--backend` option. + +* **sss_cache_dir** +The directory that stores Kerberos tickets used by SSSD. By default `/var/lib/sss/db/`. + +* **run_dir** +The run directory contains the links to the kerberos tickets for the machine and the active users. This can be overridden by the `--run-dir` option. Defaults to `/run/adsys/`. + +#### Backend specific options + +##### SSSd + +* **config** + +Path `sssd.conf`. This is the source of selected sss domain (first entry in `domains:`), to find corresponding active directory domain section. + +The option `ad_domain` in that section is used for the list of domains list of the host. `ad_server` (optional) is used as the Active directory LDAP server to contact. If it is missing, then the "Active Server" detected by sssd will be used. + +Finally `default_domain_suffix` is used too, and falls back to the domain name if missing. + +Default lookup path is `/etc/sssd/sssd.conf`. This can be overridden by the `--sssd.config` option. + +* **cache_dir** + +Path to the sss database to find the HOST kerberos ticket. Default path is `/var/lib/sss/db`. This can be overridden by the `--sssd.cache-dir` option. + +##### Winbind + +* **ad_domain** + +A custom domain can be used to override the C API call that ADSys executes to determine the active domain -- which is returned by the `wbinfo --own-domain` (e.g. `example.com`) + +* **ad_server** + +A custom domain controller can be used to override the C API call that ADSys executes to determine the AD controller FQDN -- which is returned by `wbinfo --dsgetdcname domain.com` (e.g. `adc.example.com`). + +### Client only configuration:** + +* **client_timeout** +Maximum time in seconds between 2 server activities before the client returns and aborts the request. This can be overridden by the `--timeout` option. Defaults to 30 seconds. + +## Debugging with logs (cat command) + +It is possible to follow the exchanges between all clients and the daemon with the `cat` command. It forwards all logs and message printing from the daemon alone. + +Only privileged users have access to this information. As with any other command, the verbosity can be increased with `-v` flags (it’s independent of the daemon or client current verbosity). More flags increases the verbosity further up to 3. + +More information is available in the [next chapter](adsysctl.md) covering adsysctl cat command. + +## Authorizations + +**ADSys** uses a privilege mechanism based on polkit to manage authorizations. Many commands require elevated privileges to be executed. If the adsys client is executed with insufficient privileges to execute a command, the user will be prompted to enter its password. If allowed then the command will be executed and denied otherwise. + +![Polkit authentication dialog](../images/daemon-polkit.png) + +This is configurable by the administrator as any service controlled by polkit. For more information `man polkit`. + +## Additional notes + +There are additional configuration options matching the adsysd command line options. Those are used to define things like dconf, apparmor, polkit, sudo directories... Even though they exist mostly for integration tests purposes, they can be tweaked the same way as other configuration options for the service. + +## Reference guide + +Do not hesitate to use the shell completion and the `help` subcommands to get more informations about the subcommands. diff --git a/docs/reference/adsysctl.md b/docs/reference/adsysctl.md new file mode 100644 index 000000000..e2a4a53f7 --- /dev/null +++ b/docs/reference/adsysctl.md @@ -0,0 +1,266 @@ +# The adsysctl command + +`adsysctl` is a command line utility to request actions from the daemon and query its current status. You can get more verbose output with the `-v` accumulative flags, which will stream all logs from the service corresponding to your specific request. + +As a general rule, favor shell completion and the help command for discovering various parts of the adsysctl user interface. It will help you by completing subcommands, flags, users and even chapters of the offline documentation! + +## Which policies are applied + +* You can check with policies are currently applied to your current AD user with the `adsysctl policy applied` command: + +```sh +$ adsysctl policy applied +Policies from machine configuration: +- MainOffice Policy 2 ({B8D10A86-0B78-4899-91AF-6F0124ECEB48}) +- MainOffice Policy ({C4F393CA-AD9A-4595-AEBC-3FA6EE484285}) +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) + +Policies from user configuration: +- RnD Policy 3 ({073AA7FC-5C1A-4A12-9AFC-42EC9C5CAF04}) +- RnD Policy 2 ({83A5BD5B-1D5D-472D-827F-DE0E6F714300}) +- RnD Policy ({5EC4DF8F-FF4E-41DE-846B-52AA6FFAF242}) +- IT Policy ({75545F76-DEC2-4ADA-B7B8-D5209FD48727}) +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) +``` + +The order of policies are top-down, higher GPOs have priorities over lower ones on the stack (respecting OU order, GPO enforcement, GPO block instructions on your AD setup…). + +* If you have the right permission, you can request other users as well: + +```sh +$ adsysctl policy applied tina +Policies from machine configuration: +- MainOffice Policy ({A2F393CA-AD9A-4595-AEBC-3FA6EE484285}) +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) + +Policies from user configuration: +- RnD Policy 4 ({25A5BD5B-1D5D-472D-827F-DE0E6F714300}) +- IT Policy ({75545F76-DEC2-4ADA-B7B8-D5209FD48727}) +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) +``` + +> Pro tip! Use shell completion to get the list of active users you can request which policies are applied on. + +* To get which policy are set to a given value or disabled by which key, use the `--details` flags: + +```sh +$ adsysctl policy applied --details +Policies from machine configuration: +- MainOffice Policy 2 ({B8D10A86-0B78-4899-91AF-6F0124ECEB48}) + - gdm: + - dconf/org/gnome/desktop/notifications/show-banners: Locked to system default +- MainOffice Policy ({C4F393CA-AD9A-4595-AEBC-3FA6EE484285}) + - gdm: + - dconf/org/gnome/desktop/interface/clock-format: 24h + - dconf/org/gnome/desktop/interface/clock-show-date: false + - dconf/org/gnome/desktop/interface/clock-show-weekday: true + - dconf/org/gnome/desktop/screensaver/picture-uri: 'file:///usr/share/backgrounds/ubuntu-default-greyscale-wallpaper.png' +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) + +Policies from user configuration: +- RnD Policy 3 ({073AA7FC-5C1A-4A12-9AFC-42EC9C5CAF04}) + - dconf: + - org/gnome/desktop/media-handling/automount: Locked to system default +- RnD Policy 2 ({83A5BD5B-1D5D-472D-827F-DE0E6F714300}) +- RnD Policy ({5EC4DF8F-FF4E-41DE-846B-52AA6FFAF242}) + - dconf: + - org/gnome/shell/favorite-apps: libreoffice-writer.desktop\nsnap-store_ubuntu-software.desktop\nyelp.desktop +- IT Policy ({75545F76-DEC2-4ADA-B7B8-D5209FD48727}) + - dconf: + - org/gnome/desktop/background/picture-options: stretched + - org/gnome/desktop/background/picture-uri: file:///usr/share/backgrounds/canonical.png +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) +``` + +* The `--all` flag will list every key set by a given GPO, including the ones that are redefined by another GPO with a higher priority. This is traditionally helpful for debugging your GPO stack and discover where a given value is defined: + +```sh +$ adsysctl policy applied --all +Policies from machine configuration: +- MainOffice Policy 2 ({B8D10A86-0B78-4899-91AF-6F0124ECEB48}) + - gdm: + - dconf/org/gnome/desktop/notifications/show-banners: Locked to system default +- MainOffice Policy ({C4F393CA-AD9A-4595-AEBC-3FA6EE484285}) + - gdm: + - dconf/org/gnome/desktop/interface/clock-format: 24h + - dconf/org/gnome/desktop/interface/clock-show-date: false + - dconf/org/gnome/desktop/interface/clock-show-weekday: true + - dconf/org/gnome/desktop/screensaver/picture-uri: 'file:///usr/share/backgrounds/ubuntu-default-greyscale-wallpaper.png' +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) + +Policies from user configuration: +- RnD Policy 3 ({073AA7FC-5C1A-4A12-9AFC-42EC9C5CAF04}) + - dconf: + - org/gnome/desktop/media-handling/automount: Locked to system default +- RnD Policy 2 ({83A5BD5B-1D5D-472D-827F-DE0E6F714300}) +- RnD Policy ({5EC4DF8F-FF4E-41DE-846B-52AA6FFAF242}) + - dconf: + - org/gnome/shell/favorite-apps: libreoffice-writer.desktop\nsnap-store_ubuntu-software.desktop\nyelp.desktop +- IT Policy ({75545F76-DEC2-4ADA-B7B8-D5209FD48727}) + - dconf: + - org/gnome/desktop/background/picture-options: stretched + - org/gnome/desktop/background/picture-uri: file:///usr/share/backgrounds/canonical.png + - org/gnome/shell/favorite-apps: 'firefox.desktop'\n'thunderbird.desktop'\n'org.gnome.Nautilus.desktop' +- Default Domain Policy ({31B2F340-016D-11D2-945F-00C04FB984F9}) +``` + +## Refreshing the policies + +The command `adsysctl policy update` is used to refresh the policies. By default only the policy of the current user is updated. It can also refresh only the policy of the machine with the flag `-m`, or the machine and all the active users with the flag `-a`. On success nothing is displayed. + +For example, refreshing the policy for all the objects: + +```sh +$ adsysctl policy update --all -v +INFO No configuration file: Config File "adsys" Not Found in "[/home/warthogs.biz/b/bob /etc]". +We will only use the defaults, env variables or flags. +INFO Apply policy for adclient04 (machine: true) +INFO Apply policy for bob@warthogs.biz (machine: false) +``` + +You can provide the name of a user and the path to its Kerberos ticket to refresh a given user. + +For example for user `bob@warthogs.biz` + +```sh +$ adsysctl update bob@warthogs.biz /tmp/krb5cc_1899001102_wBlbck -vv +INFO No configuration file: Config File "adsys" Not Found in "[/home/warthogs.biz/b/bob /etc]". +We will only use the defaults, env variables or flags. +DEBUG Connecting as [[26812:519495]] +DEBUG New request /service/UpdatePolicy +DEBUG Requesting with parameters: IsComputer: false, All: false, Target: bob@warthogs.biz, Krb5Cc: /tmp/krb5cc_1899001102_wBlbck +DEBUG Check if grpc request peer is authorized +DEBUG Polkit call result, authorized: true +DEBUG GetPolicies for "bob@warthogs.biz", type "user" +DEBUG GPO "RnD Policy 3" for "bob@warthogs.biz" available at "smb://warthogs.biz/SysVol/warthogs.biz/Policies/{073AA7FC-5C1A-4A12-9AFC-42EC9C5CAF04}" +DEBUG GPO "RnD Policy 2" for "bob@warthogs.biz" available at "smb://warthogs.biz/SysVol/warthogs.biz/Policies/{83A5BD5B-1D5D-472D-827F-DE0E6F714300}" +DEBUG GPO "RnD Policy" for "bob@warthogs.biz" available at "smb://warthogs.biz/SysVol/warthogs.biz/Policies/{5EC4DF8F-FF4E-41DE-846B-52AA6FFAF242}" +DEBUG GPO "IT Policy" for "bob@warthogs.biz" available at "smb://warthogs.biz/SysVol/warthogs.biz/Policies/{75545F76-DEC2-4ADA-B7B8-D5209FD48727}" +DEBUG GPO "Default Domain Policy" for "bob@warthogs.biz" available at "smb://warthogs.biz/sysvol/warthogs.biz/Policies/{31B2F340-016D-11D2-945F-00C04FB984F9}" +DEBUG Analyzing GPO "Default Domain Policy" +DEBUG Analyzing GPO "IT Policy" +DEBUG Analyzing GPO "RnD Policy 2" +DEBUG Analyzing GPO "RnD Policy 3" +DEBUG Analyzing GPO "RnD Policy" +DEBUG Policy "RnD Policy 2" doesn't have any policy for class "user" open /var/cache/adsys/gpo_cache/{83A5BD5B-1D5D-472D-827F-DE0E6F714300}/User/Registry.pol: no such file or directory +DEBUG Policy "Default Domain Policy" doesn't have any policy for class "user" open /var/cache/adsys/gpo_cache/{31B2F340-016D-11D2-945F-00C04FB984F9}/User/Registry.pol: no such file or directory +INFO Apply policy for bob@warthogs.biz (machine: false) +DEBUG ApplyPolicy dconf policy to bob@warthogs.biz +DEBUG Update user profile /etc/dconf/profile/bob@warthogs.biz +DEBUG Analyzing entry {Key:org/gnome/desktop/background/picture-options Value:stretched Disabled:false Meta:s} +DEBUG Analyzing entry {Key:org/gnome/desktop/background/picture-uri Value:file:///usr/share/backgrounds/canonical.png Disabled:false Meta:s} +DEBUG Analyzing entry {Key:org/gnome/desktop/media-handling/automount Value: Disabled:true Meta:} +DEBUG Analyzing entry {Key:org/gnome/shell/favorite-apps Value:libreoffice-writer.desktop +snap-store_ubuntu-software.desktop +yelp.desktop + Disabled:false Meta:as} +``` + +## Getting the status + +The status of the service is provided by the command `adsysctl service status` + +```sh +$ adsysctl service status +Machine, updated on Tue May 18 12:15 +Connected users: + bob@warthogs.biz, updated on Tue May 18 12:15 + +Active Directory: + Server: ldap://adc01.warthogs.biz + Domain: warthogs.biz + +SSS: + Configuration: /etc/sssd/sssd.conf + Cache directory: /var/lib/sss/db + +Daemon: + Timeout after 2m0s + Listening on: /run/adsysd.sock + Cache path: /var/cache/adsys + Run path: /run/adsys + Dconf path: /etc/dconf +``` + +You can get the list of connected users, when they were last refreshed, when the next refresh is scheduled and various service configuration options (static or dynamically configured). + +## Debugging + +The `cat` command has already been described in [the previous chapter](adsys-daemon.md). You can display logs with debugging levels independent of daemon and clients debugging levels. Local printing will also be forwarded. + +For example, running `cat` while the command `version` and `applied` are executed: + +```sh +# adsysctl service cat -vv +INFO No configuration file: Config File "adsys" Not Found in "[/root /etc]". +We will only use the defaults, env variables or flags. +DEBUG Connecting as [[29220:823925]] +DEBUG New request /service/Cat +DEBUG Requesting with parameters: +DEBUG Check if grpc request peer is authorized +DEBUG Authorized as being administrator +INFO New connection from client [[29302:462445]] +DEBUG [[29302:462445]] New request /service/Version +DEBUG [[29302:462445]] Requesting with parameters: +DEBUG [[29302:462445]] Check if grpc request peer is authorized +DEBUG [[29302:462445]] Any user always authorized +DEBUG Request /service/Version done +INFO New connection from client [[29455:217212]] +DEBUG [[29455:217212]] New request /service/DumpPolicies +DEBUG [[29455:217212]] Requesting with parameters: Target: bob@warthogs.biz, Details: false, All: false +DEBUG [[29455:217212]] Check if grpc request peer is authorized +DEBUG [[29455:217212]] Polkit call result, authorized: true +INFO [[29455:217212]] Dumping policies for bob@warthogs.biz +DEBUG Request /service/DumpPolicies done +``` + +## Other commands + +### Versions + +You can get the current service and client versions with the `version` command to check you are running with latest version on both sides: + +```sh +$ adsysctl version +adsysctl 0.5 +adsysd 0.5 +``` + +### Documentation + +An offline version of this documentation is available in the deamon. It will render the documentation on the command line. + +You can get a list of all chapters with their titles: + +```sh +$ adysctl doc + + Table of content + + 1. [Welcome] ADSys: Active Directory Group Policy integration + 2. [Prerequisites] Prerequisites and installation +[…] +``` + +And render a given chapter by requesting it: + +```sh +$ adsysctl doc Welcome + + ADSys: Active Directory Group Policy integration + + ADSys is the Active Directory Group Policy client for Ubuntu. It allows +[…] +``` + +Finally, there are different rendering modes to dump documentation in html for instance with the `--format` flag. + +### Admx generation + +The `policy admx` commands dumps pre-built Active Directory administrative templates that can be deployed on the Active Directory server. For more information, check the [AD setup documentation](../how-to/set-up-ad.md) + +### Stopping the service + +If you do not wish to wait for the idling timeout to stop the server, you can request graceful shutdown with `adsysctl service stop`. This will first wait for all active connections to ends before shutting down. + +The `-force` flag will end the service immediately. diff --git a/docs/cli-reference.md b/docs/reference/cli-reference.md similarity index 100% rename from docs/cli-reference.md rename to docs/reference/cli-reference.md diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 000000000..e2ef628c4 --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1,20 @@ +# Technical Reference + +Technical information - specifications, APIs, architecture + +## Commands + +This is the configuration needed on Windows Domain Controller. + +```{toctree} +:titlesonly: +adsysd +adsysctl command +``` + +## Reference + +```{toctree} +:titlesonly: +CLI reference +```