From ab9883f4bfbc33d0a9c4ce9ab26878272c5c8e63 Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Mon, 4 Aug 2025 16:14:40 +0200 Subject: [PATCH 1/3] Automatically formatted markdown files. Signed-off-by: Ole Herman Schumacher Elgesem --- cheatsheet.markdown | 1 - content/_index.markdown | 1 + content/api/_index.markdown | 2 +- .../enterprise-api-examples/_index.markdown | 14 +- .../browsing-host-information.markdown | 2 +- .../changes-api-usage.markdown | 6 +- .../checking-status.markdown | 2 +- .../managing-settings.markdown | 2 +- .../managing-users-and-roles.markdown | 2 +- .../sql-queries.markdown | 2 +- .../api/enterprise-api-ref/_index.markdown | 8 +- .../enterprise-api-ref/actions-api.markdown | 6 +- .../audit-logs-api.markdown | 48 +- .../api/enterprise-api-ref/build-api.markdown | 146 +-- .../api/enterprise-api-ref/changes.markdown | 168 ++-- .../api/enterprise-api-ref/cmdb-api.markdown | 70 +- .../export-import-api.markdown | 66 +- ...port-import-compliance-report-api.markdown | 157 +-- .../federated-reporting-api.markdown | 52 +- .../enterprise-api-ref/file-changes.markdown | 28 +- .../first-time-setup.markdown | 40 +- .../health-diagnostic.markdown | 70 +- content/api/enterprise-api-ref/host.markdown | 168 ++-- .../api/enterprise-api-ref/inventory.markdown | 140 +-- .../api/enterprise-api-ref/ldap-api.markdown | 96 +- .../personal-groups.markdown | 97 +- content/api/enterprise-api-ref/query.markdown | 48 +- .../reset-password.markdown | 12 +- .../enterprise-api-ref/shared-groups.markdown | 119 +-- .../sql-schema/cfdb.markdown | 892 +++++++++--------- .../sql-schema/cfmp.markdown | 331 +++---- .../sql-schema/cfsettings.markdown | 290 +++--- .../enterprise-api-ref/ssh-keys-api.markdown | 36 +- .../status-settings.markdown | 94 +- .../two-factor-authentication.markdown | 33 +- .../enterprise-api-ref/users-rbac.markdown | 148 +-- .../enterprise-api-ref/vcs-settings.markdown | 33 +- .../api/enterprise-api-ref/web-rbac.markdown | 54 +- .../install-get-started.markdown | 6 +- content/examples/_index.markdown | 108 +-- .../examples/example-snippets/_index.markdown | 30 +- .../basic-file-directory.markdown | 56 +- .../cfengine-administration.markdown | 4 +- .../commands-scripts-execution.markdown | 14 +- .../example-snippets/database.markdown | 2 +- .../example-snippets/file-template.markdown | 2 +- .../example-snippets/general.markdown | 6 +- .../example-snippets/network.markdown | 18 +- .../promise-patterns/_index.markdown | 36 +- .../example_aborting_execution.markdown | 4 +- .../example_edit_motd.markdown | 14 +- .../example_enable_service.markdown | 16 +- .../example_install_package.markdown | 3 +- .../example_mount_nfs.markdown | 4 +- .../example_process_restart.markdown | 2 +- ...example_updating_from_central_hub.markdown | 4 +- .../software-adminstration.markdown | 22 +- .../system-administration.markdown | 2 +- .../system-information.markdown | 14 +- .../example-snippets/system-security.markdown | 6 +- .../timing-counting-measuring.markdown | 2 +- .../example-snippets/user-management.markdown | 3 +- .../windows-registry.markdown | 6 +- .../tutorials/custom_inventory.markdown | 8 +- ...ute-files-from-a-central-location.markdown | 13 +- .../tutorials/file_comparison.markdown | 3 +- .../tutorials/files-tutorial.markdown | 19 +- .../high-availability/_index.markdown | 4 +- .../installation-guide.markdown | 102 +- ...talling-cfengine-enterprise-agent.markdown | 15 +- ...ntegrating-alerts-with-pager-duty.markdown | 20 +- ...ing-alerts-with-ticketing-systems.markdown | 16 +- .../integrating-with-sumo-logic.markdown | 13 +- .../json-yaml-support-in-cfengine.markdown | 36 +- .../examples/tutorials/manage-ntp.markdown | 16 +- ...ory_remediate_sec_vulnerabilities.markdown | 16 +- .../tutorials/reporting/_index.markdown | 14 +- .../reporting/command-line-reports.markdown | 12 +- content/examples/tutorials/tags.markdown | 36 +- .../tutorials/write-cfengine-policy.markdown | 10 +- .../_index.markdown | 25 +- ...thoring-policy-tools-and-workflow.markdown | 17 +- .../bundles-best-practices.markdown | 62 +- .../controlling-frequency.markdown | 8 +- .../editors.markdown | 4 +- .../policy-layers-abstraction.markdown | 2 +- .../policy-style.markdown | 37 +- .../testing-policies.markdown | 1 + .../developing-modules.markdown | 22 +- .../installation/_index.markdown | 16 +- .../general-installation/_index.markdown | 36 +- .../common_next_steps.include.markdown | 12 +- ...tallation-community-containerized.markdown | 22 +- .../installation-community.markdown | 17 +- .../installation-coreos.markdown | 12 +- ...allation-enterprise-free-aws-rhel.markdown | 134 +-- .../installation-enterprise-free.markdown | 42 +- .../installation-enterprise-vagrant.markdown | 22 +- .../installation-enterprise.markdown | 46 +- .../installation-overview.markdown | 12 +- .../local-virtual-machine.markdown | 12 +- .../_index.markdown | 8 +- .../putty-quick-start-guide.markdown | 104 +- .../vi-quick-start-guide.markdown | 2 +- .../installation/secure-bootstrap.markdown | 18 +- .../installation/upgrading.markdown | 5 +- .../modules-from-cfengine-build.markdown | 6 +- .../getting-started/writing-policy.markdown | 12 +- content/guide/_index.markdown | 46 +- content/overview/_index.markdown | 22 +- .../client-server-communication.markdown | 16 +- content/overview/directory-structure.markdown | 174 ++-- content/overview/glossary.markdown | 12 +- content/overview/how-cfengine-works.markdown | 51 +- content/reference/_index.markdown | 20 +- content/reference/all-types.markdown | 4 +- content/reference/components/_index.markdown | 33 +- .../reference/components/cf-agent.markdown | 81 +- .../reference/components/cf-execd.markdown | 12 +- content/reference/components/cf-hub.markdown | 12 +- content/reference/components/cf-key.markdown | 2 +- .../reference/components/cf-monitord.markdown | 160 ++-- content/reference/components/cf-net.markdown | 12 +- .../reference/components/cf-promises.markdown | 6 +- .../reference/components/cf-reactor.markdown | 8 +- .../reference/components/cf-runagent.markdown | 6 +- .../reference/components/cf-secret.markdown | 2 +- .../reference/components/cf-serverd.markdown | 46 +- .../reference/components/cf-support.markdown | 2 +- content/reference/functions/_index.markdown | 66 +- .../reference/functions/accumulated.markdown | 12 +- content/reference/functions/ago.markdown | 12 +- content/reference/functions/and.markdown | 4 +- .../functions/bundlesmatching.markdown | 4 +- .../reference/functions/bundlestate.markdown | 2 +- .../functions/callstack_callers.markdown | 12 +- .../functions/canonifyuniquely.markdown | 2 +- .../functions/cf_version_after.markdown | 2 +- .../functions/cf_version_at.markdown | 2 +- .../functions/cf_version_before.markdown | 2 +- .../functions/cf_version_between.markdown | 2 +- .../functions/cf_version_maximum.markdown | 2 +- .../functions/cf_version_minimum.markdown | 2 +- .../functions/classfiltercsv.markdown | 18 +- .../functions/classfilterdata.markdown | 1 + .../functions/data_readstringarray.markdown | 4 +- .../data_readstringarrayidx.markdown | 2 +- .../functions/data_regextract.markdown | 4 +- .../reference/functions/datastate.markdown | 18 +- content/reference/functions/eval.markdown | 22 +- content/reference/functions/every.markdown | 8 +- .../reference/functions/execresult.markdown | 8 +- .../functions/execresult_as_data.markdown | 2 +- .../reference/functions/expandrange.markdown | 2 +- .../reference/functions/filesexist.markdown | 4 +- content/reference/functions/filestat.markdown | 50 +- content/reference/functions/filter.markdown | 12 +- .../reference/functions/findfiles.markdown | 22 +- .../reference/functions/findfiles_up.markdown | 22 +- .../functions/findlocalusers.markdown | 17 +- content/reference/functions/format.markdown | 10 +- .../functions/getbundlemetatags.markdown | 2 +- .../functions/getclassmetatags.markdown | 4 +- .../reference/functions/getfields.markdown | 14 +- content/reference/functions/getusers.markdown | 6 +- .../reference/functions/getvalues.markdown | 4 +- .../functions/getvariablemetatags.markdown | 4 +- content/reference/functions/grep.markdown | 2 +- content/reference/functions/host2ip.markdown | 2 +- content/reference/functions/ifelse.markdown | 4 +- content/reference/functions/int.markdown | 4 +- content/reference/functions/irange.markdown | 40 +- content/reference/functions/is_type.markdown | 2 +- .../functions/isconnectable.markdown | 2 +- .../reference/functions/isreadable.markdown | 2 +- content/reference/functions/lsdir.markdown | 2 +- content/reference/functions/maparray.markdown | 2 +- .../reference/functions/mergedata.markdown | 6 +- .../functions/network_connections.markdown | 8 +- content/reference/functions/not.markdown | 6 +- content/reference/functions/now.markdown | 12 +- content/reference/functions/nth.markdown | 6 +- content/reference/functions/or.markdown | 4 +- .../functions/packagesmatching.markdown | 10 +- .../functions/packageupdatesmatching.markdown | 10 +- .../functions/parseintarray.markdown | 16 +- .../reference/functions/parsejson.markdown | 6 +- .../functions/parserealarray.markdown | 14 +- .../functions/parsestringarray.markdown | 14 +- .../reference/functions/peerleaders.markdown | 2 +- .../reference/functions/randomint.markdown | 4 +- content/reference/functions/readfile.markdown | 12 +- .../reference/functions/readintarray.markdown | 16 +- content/reference/functions/readjson.markdown | 2 +- .../functions/readrealarray.markdown | 17 +- .../reference/functions/readreallist.markdown | 12 +- .../functions/readstringarray.markdown | 17 +- .../functions/readstringarrayidx.markdown | 2 +- .../functions/readstringlist.markdown | 12 +- content/reference/functions/readtcp.markdown | 2 +- .../functions/regex_replace.markdown | 14 +- .../functions/remoteclassesmatching.markdown | 2 +- .../reference/functions/remotescalar.markdown | 2 +- .../reference/functions/returnszero.markdown | 4 +- content/reference/functions/reverse.markdown | 4 +- .../functions/selectservers.markdown | 2 +- content/reference/functions/sort.markdown | 9 +- .../reference/functions/splayclass.markdown | 8 +- .../reference/functions/splitstring.markdown | 2 +- .../reference/functions/storejson.markdown | 4 +- content/reference/functions/string.markdown | 4 +- .../reference/functions/string_split.markdown | 4 +- content/reference/functions/type.markdown | 4 +- content/reference/functions/url_get.markdown | 30 +- .../reference/functions/usemodule.markdown | 1 + .../functions/variablesmatching.markdown | 2 +- .../variablesmatching_as_data.markdown | 2 +- .../functions/version_compare.markdown | 2 +- .../language-concepts/_index.markdown | 60 +- .../language-concepts/augments.markdown | 98 +- .../language-concepts/bodies.markdown | 4 +- .../language-concepts/bundles.markdown | 29 +- .../language-concepts/classes.markdown | 240 ++--- .../language-concepts/loops.markdown | 2 +- .../language-concepts/modules/_index.markdown | 50 +- .../modules/package-module-api.markdown | 30 +- .../language-concepts/namespaces.markdown | 4 +- .../policy-evaluation.markdown | 8 +- .../language-concepts/promises.markdown | 22 +- .../language-concepts/variables.markdown | 32 +- content/reference/macros.markdown | 16 +- .../masterfiles-policy-framework/lib.markdown | 4 +- .../modules-packages-vendored.markdown | 1 + .../modules-packages.markdown | 1 + .../modules-promises.markdown | 1 + .../modules.markdown | 1 + .../standalone_self_upgrade.markdown | 2 +- .../reference/promise-types/_index.markdown | 94 +- .../reference/promise-types/access.markdown | 22 +- .../reference/promise-types/classes.markdown | 31 +- .../reference/promise-types/commands.markdown | 47 +- .../reference/promise-types/custom.markdown | 168 ++-- .../promise-types/databases.markdown | 29 +- .../reference/promise-types/defaults.markdown | 2 +- .../promise-types/files/_index.markdown | 287 +++--- .../files/edit_line/_index.markdown | 119 +-- .../files/edit_line/delete_lines.markdown | 14 +- .../files/edit_line/field_edits.markdown | 18 +- .../files/edit_line/insert_lines.markdown | 28 +- .../files/edit_line/replace_patterns.markdown | 8 +- .../files/edit_xml/_index.markdown | 3 +- .../promise-types/guest_environments.markdown | 22 +- .../promise-types/measurements.markdown | 26 +- .../reference/promise-types/methods.markdown | 4 +- .../packages-deprecated.markdown | 92 +- .../reference/promise-types/packages.markdown | 59 +- .../promise-types/processes.markdown | 8 +- .../reference/promise-types/reports.markdown | 4 +- .../reference/promise-types/roles.markdown | 2 +- .../reference/promise-types/services.markdown | 30 +- .../reference/promise-types/storage.markdown | 17 +- .../reference/promise-types/users.markdown | 2 +- content/reference/promise-types/vars.markdown | 29 +- .../special-variables/_index.markdown | 36 +- .../special-variables/const.markdown | 2 +- .../reference/special-variables/edit.markdown | 4 +- .../special-variables/match.markdown | 2 +- .../reference/special-variables/sys.markdown | 57 +- .../reference/special-variables/this.markdown | 20 +- content/release-notes/_index.markdown | 6 +- .../release-notes/legal-and-licenses.markdown | 150 +-- .../supported-platforms.markdown | 38 +- .../release-notes/whatsnew/_index.markdown | 6 +- .../additional-topics/agility.markdown | 192 ++-- .../application-management.markdown | 32 +- .../build-deploy-manage-audit.markdown | 96 +- .../change-management.markdown | 53 +- .../cloud-computing.markdown | 22 +- .../content-driven-policy.markdown | 12 +- .../additional-topics/devops.markdown | 15 +- .../distributed-scheduling.markdown | 18 +- .../additional-topics/file-content.markdown | 95 +- .../additional-topics/hierarchies.markdown | 37 +- .../additional-topics/iteration.markdown | 4 +- .../resources/additional-topics/itil.markdown | 149 ++- .../additional-topics/modularity.markdown | 22 +- .../additional-topics/open-nebula.markdown | 19 +- .../additional-topics/orchestration.markdown | 12 +- .../additional-topics/security.markdown | 89 +- .../additional-topics/stigs.markdown | 6 +- .../additional-topics/teamwork.markdown | 26 +- content/resources/best-practices.markdown | 27 +- content/resources/external-resources.markdown | 62 +- .../resources/faq/bootstrap-failed.markdown | 18 +- .../faq/enterprise-report-collection.markdown | 10 +- .../faq/enterprise-report-filtering.markdown | 2 +- content/resources/faq/enterprise.markdown | 8 +- content/resources/faq/fhs.markdown | 11 +- .../faq/fix-undefined-body-error.markdown | 1 + .../faq/integrate-custom-policy.markdown | 66 +- .../resources/faq/manual-execution.markdown | 2 +- .../faq/mustache-templating.markdown | 18 +- .../faq/show-classes-and-vars.markdown | 4 +- .../resources/faq/tuning-postgresql.markdown | 24 +- .../unable-to-log-in-mission-portal.markdown | 6 +- .../faq/what-did-cfengine-change.markdown | 2 +- ...hy-are-remote-agents-not-updating.markdown | 8 +- content/web-ui/_index.markdown | 18 +- .../web-ui/alerts-and-notifications.markdown | 42 +- .../web-ui/custom-actions-for-alerts.markdown | 46 +- .../web-ui/debugging-mission-portal.markdown | 7 +- .../enterprise-reporting/_index.markdown | 20 +- .../reporting-architecture.markdown | 10 +- .../reporting_ui.markdown | 92 +- .../sql-queries-enterprise-api.markdown | 12 +- content/web-ui/federated-reporting.markdown | 349 +++---- content/web-ui/health.markdown | 12 +- content/web-ui/hosts.markdown | 12 +- .../backup-and-restore.markdown | 4 +- .../decommissioning-hosts.markdown | 24 +- .../extending-mission-portal.markdown | 8 +- .../extending-query-builder.markdown | 54 +- .../policy-deployment.markdown | 1 + content/web-ui/measurements.markdown | 10 +- content/web-ui/settings.markdown | 33 +- 325 files changed, 5291 insertions(+), 5144 deletions(-) diff --git a/cheatsheet.markdown b/cheatsheet.markdown index beed7b894..339c67597 100644 --- a/cheatsheet.markdown +++ b/cheatsheet.markdown @@ -596,7 +596,6 @@ site.CFE_manuals_version {{ site.CFE_manuals_version }} ### Indention with included markdown 1. Verify that the selected hosts are upgrading successfully. - - Mission Portal [Inventory reporting interface][Reporting UI#inventory management] - [Inventory API][Inventory API] diff --git a/content/_index.markdown b/content/_index.markdown index edb52d195..f4fa25229 100644 --- a/content/_index.markdown +++ b/content/_index.markdown @@ -5,6 +5,7 @@ sorting: 1 categories: ["index"] alias: index.html --- +

Welcome to the CFEngine Documentation

diff --git a/content/api/_index.markdown b/content/api/_index.markdown index 1115f9dd2..0b033b981 100644 --- a/content/api/_index.markdown +++ b/content/api/_index.markdown @@ -5,7 +5,7 @@ sorting: 50 --- The CFEngine Enterprise API allows HTTP clients to interact with the -CFEngine Enterprise *Hub*. Typically this is also the policy server. +CFEngine Enterprise _Hub_. Typically this is also the policy server. ![Enterprise API Overview](enterprise-api-architecture-overview.png) diff --git a/content/api/enterprise-api-examples/_index.markdown b/content/api/enterprise-api-examples/_index.markdown index cef678e45..d6252bfcf 100644 --- a/content/api/enterprise-api-examples/_index.markdown +++ b/content/api/enterprise-api-examples/_index.markdown @@ -4,12 +4,12 @@ title: Enterprise API examples sorting: 6 --- -* [Check installation status][Checking status] -* [Manage users, roles][Managing users and roles] -* [Managing settings][Managing settings] -* [Browse host information][Browsing host information] -* [Issue flexible SQL queries][SQL query examples] against data collected from hosts by the CFEngine Server -* [Schedule reports][SQL query examples#Subscribed query example: Creating a subscribed query] for email and later download -* [Tracking changes performed by CFEngine][Tracking changes] +- [Check installation status][Checking status] +- [Manage users, roles][Managing users and roles] +- [Managing settings][Managing settings] +- [Browse host information][Browsing host information] +- [Issue flexible SQL queries][SQL query examples] against data collected from hosts by the CFEngine Server +- [Schedule reports][SQL query examples#Subscribed query example: Creating a subscribed query] for email and later download +- [Tracking changes performed by CFEngine][Tracking changes] **See also:** [Enterprise API reference][Enterprise API reference] diff --git a/content/api/enterprise-api-examples/browsing-host-information.markdown b/content/api/enterprise-api-examples/browsing-host-information.markdown index decbfaeac..99a4cb05c 100644 --- a/content/api/enterprise-api-examples/browsing-host-information.markdown +++ b/content/api/enterprise-api-examples/browsing-host-information.markdown @@ -40,7 +40,7 @@ gathered from `cf-monitord`) is not part of the SQL reports data model. ## Example: Looking up hosts by hostname -Contexts, also known as classes, are powerful. You can use them to +Contexts, also known as classes, are powerful. You can use them to categorize hosts according to a rich set of tags. For example, each host is automatically tagged with a canonicalized version of its hostname and IP-address. So we could lookup the host with hostname diff --git a/content/api/enterprise-api-examples/changes-api-usage.markdown b/content/api/enterprise-api-examples/changes-api-usage.markdown index 299da06af..6388b7b2c 100644 --- a/content/api/enterprise-api-examples/changes-api-usage.markdown +++ b/content/api/enterprise-api-examples/changes-api-usage.markdown @@ -10,7 +10,7 @@ Changes REST API allows to track the changes made by cf-agent in the infrastruct This examples shows how to count changes performed by cf-agent within last 24h hours. -Example is searching for changes that are performed by *linux* machines within *generate_repairs* bundle. +Example is searching for changes that are performed by _linux_ machines within _generate_repairs_ bundle. **Request** @@ -28,9 +28,9 @@ curl --user admin:admin 'https://test.cfengine.com/api/v2/changes/policy/count?i ## Example: Show vacuum command executions -Show all *vacuumdb* executions within last 24 hours executed on hosts reporting the `policy_server` or `test_cfengine_com` class. +Show all _vacuumdb_ executions within last 24 hours executed on hosts reporting the `policy_server` or `test_cfengine_com` class. -Example is searching for changes that are performed by *policy_server* machines that execute *commands* promise with command */var/cfengine/bin/vacuumdb%* - there is `%` sign at the end which is a wildcard as `vacuumdb` is executed with different options across policy. +Example is searching for changes that are performed by _policy_server_ machines that execute _commands_ promise with command _/var/cfengine/bin/vacuumdb%_ - there is `%` sign at the end which is a wildcard as `vacuumdb` is executed with different options across policy. **Request** diff --git a/content/api/enterprise-api-examples/checking-status.markdown b/content/api/enterprise-api-examples/checking-status.markdown index 3c9d54bbd..8e175da58 100644 --- a/content/api/enterprise-api-examples/checking-status.markdown +++ b/content/api/enterprise-api-examples/checking-status.markdown @@ -1,6 +1,6 @@ --- layout: default -title: Checking status +title: Checking status sorting: 20 --- diff --git a/content/api/enterprise-api-examples/managing-settings.markdown b/content/api/enterprise-api-examples/managing-settings.markdown index c7bd69aaa..b9ef3087c 100644 --- a/content/api/enterprise-api-examples/managing-settings.markdown +++ b/content/api/enterprise-api-examples/managing-settings.markdown @@ -1,6 +1,6 @@ --- layout: default -title: Managing settings +title: Managing settings sorting: 30 --- diff --git a/content/api/enterprise-api-examples/managing-users-and-roles.markdown b/content/api/enterprise-api-examples/managing-users-and-roles.markdown index f29bf8c65..07e66d226 100644 --- a/content/api/enterprise-api-examples/managing-users-and-roles.markdown +++ b/content/api/enterprise-api-examples/managing-users-and-roles.markdown @@ -1,6 +1,6 @@ --- layout: default -title: Managing users and roles +title: Managing users and roles sorting: 40 --- diff --git a/content/api/enterprise-api-examples/sql-queries.markdown b/content/api/enterprise-api-examples/sql-queries.markdown index f72d6e9ed..d03bbf1be 100644 --- a/content/api/enterprise-api-examples/sql-queries.markdown +++ b/content/api/enterprise-api-examples/sql-queries.markdown @@ -1,6 +1,6 @@ --- layout: default -title: SQL query examples +title: SQL query examples --- ### Synchronous Example: Listing hostname and IP for Ubuntu hosts diff --git a/content/api/enterprise-api-ref/_index.markdown b/content/api/enterprise-api-ref/_index.markdown index 675ba318b..448317e4d 100644 --- a/content/api/enterprise-api-ref/_index.markdown +++ b/content/api/enterprise-api-ref/_index.markdown @@ -1,6 +1,6 @@ --- layout: default -title: Enterprise API reference +title: Enterprise API reference sorting: 70 --- @@ -77,15 +77,15 @@ Enterprise API responses are always of the following format, consisting of a If the response is not `200 OK`, the appropriate HTTP error code returned along with a (possibly non-JSON) payload. -All timestamps are reported in *Unix Time*, i.e. seconds since 1970. +All timestamps are reported in _Unix Time_, i.e. seconds since 1970. ## Authentication The API supports both internal and external authentication. The internal users table will always be consulted first, followed by an external source specified -in the settings. External sources are *OpenLDAP* or *Active Directory* servers +in the settings. External sources are _OpenLDAP_ or _Active Directory_ servers configurable through [/api/settings][Status and settings REST API#Update settings]. ## Authorization -Some resources require that the request user is a member of the *admin* role. Roles are managed with [/api/role][Users and access-control REST API#List RBAC roles]. Role Based Access Control (RBAC) is configurable through the settings. Users typically have permission to access their own resources, e.g. their own scheduled reports. +Some resources require that the request user is a member of the _admin_ role. Roles are managed with [/api/role][Users and access-control REST API#List RBAC roles]. Role Based Access Control (RBAC) is configurable through the settings. Users typically have permission to access their own resources, e.g. their own scheduled reports. diff --git a/content/api/enterprise-api-ref/actions-api.markdown b/content/api/enterprise-api-ref/actions-api.markdown index 420e5c10b..1702a4a3d 100644 --- a/content/api/enterprise-api-ref/actions-api.markdown +++ b/content/api/enterprise-api-ref/actions-api.markdown @@ -15,8 +15,8 @@ You can trigger a delta report collection in order to have fresh host data. **Parameters:** -* **hostkey** *(string)* - Unique host identifier +- **hostkey** _(string)_ + Unique host identifier **Example request (curl):** @@ -44,7 +44,7 @@ You can trigger an agent run for an individual host. **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier **Example request (curl):** diff --git a/content/api/enterprise-api-ref/audit-logs-api.markdown b/content/api/enterprise-api-ref/audit-logs-api.markdown index 808d077e3..6a7bc99d7 100644 --- a/content/api/enterprise-api-ref/audit-logs-api.markdown +++ b/content/api/enterprise-api-ref/audit-logs-api.markdown @@ -14,34 +14,34 @@ such as settings, host data, users, roles, Build projects, etc. **Parameters:** -* **actor** *(string)* +- **actor** _(string)_ Filter by user who performed the action. -* **object_type** *(string)* +- **object_type** _(string)_ Filter by object type (see [Allowed object types][Audit log API#Allowed object types]). -* **action** *(string)* +- **action** _(string)_ Filter by action type (see [Allowed actions][Audit log API#Allowed actions]). -* **object_name** *(integer)* +- **object_name** _(integer)_ Filter by object name. -* **created_after** *(integer)* +- **created_after** _(integer)_ Unix timestamp to filter logs after this time. -* **created_before** *(integer)* +- **created_before** _(integer)_ Unix timestamp to filter logs before this time. -* **page** *(integer)* +- **page** _(integer)_ Page number for pagination (default: 1). -* **offset** *(integer)* - Number of results to skip for the processed query. -* **sort_column** *(string)* - Column to sort by. Allowed values: - * time - * actor - * action - * object_id - * object_name - * object_type -* **sort_direction** *(string, default: "DESC")* +- **offset** _(integer)_ + Number of results to skip for the processed query. +- **sort_column** _(string)_ + Column to sort by. Allowed values: + - time + - actor + - action + - object_id + - object_name + - object_type +- **sort_direction** _(string, default: "DESC")_ Sort direction. Allowed values: - * ASC (ascending) - * DESC (descending) + - ASC (ascending) + - DESC (descending) **Example request (curl):** @@ -114,7 +114,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|------------------------------|--------------------------------------| +| ---------------------------- | ------------------------------------ | | 200 OK | Audit logs returned | | 422 Unprocessable entity | Validation error occurred | | 401 Unauthorized | Authorization is missing | @@ -124,7 +124,7 @@ HTTP 200 OK ### Allowed actions | Action | Description | -|----------------------|---------------------------| +| -------------------- | ------------------------- | | Created | Resource creation | | Updated | Resource update | | Deleted | Resource deletion | @@ -142,7 +142,7 @@ HTTP 200 OK ### Allowed object types | Object Type | Description | -|---------------------|----------------------------------------------| +| ------------------- | -------------------------------------------- | | User | User account | | Role | Role definition | | Settings | System, Mail, VCS or Authentication settings | @@ -185,7 +185,7 @@ Returns list of object names filtered by type. **Parameters:** -* **object_type** *(string)* +- **object_type** _(string)_ Filter by object type (see [Allowed object types][Audit log API#Allowed object types]). **Example request (curl):** diff --git a/content/api/enterprise-api-ref/build-api.markdown b/content/api/enterprise-api-ref/build-api.markdown index 768e1cdca..87ba38e36 100644 --- a/content/api/enterprise-api-ref/build-api.markdown +++ b/content/api/enterprise-api-ref/build-api.markdown @@ -17,25 +17,25 @@ A project is a set of CFEngine Build modules and custom files/json/policy files. **Parameters:** -* **repositoryUrl** *(string)* +- **repositoryUrl** _(string)_ Git repository URL. Project will be synchronized with this repository. Supported protocols: `http`, `https`, `ssh` , `git`. Required. Git repository URL example: https://github.com/username/repository.git -* **branch** *(string)* +- **branch** _(string)_ Repository branch. Required. -* **name** *(string)* +- **name** _(string)_ Project name. Required. -* **authenticationType** *(string)* +- **authenticationType** _(string)_ Authentication type that will be used to get access to the repository. Allowed values: `password`, `private_key`. Required. -* **username** *(string)* +- **username** _(string)_ Username for authentication to the repository. Required when authentication type is `password`. -* **password** *(string)* +- **password** _(string)_ Password for authentication to the repository. Required when authentication type is `password`. -* **sshPrivateKey** *(string)* +- **sshPrivateKey** _(string)_ SSH private key for authentication to the repository. Required when authentication type is `private_key` and `sshKeyId` is not set. -* **sshKeyId** *(integer)* +- **sshKeyId** _(integer)_ Generated SSH private key ID by [SSH keys API][SSH keys API#Generate SSH key] for authentication to the repository. Required when authentication type is `private_key` and `sshPrivateKey` is not set. @@ -75,7 +75,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|------------------------------| +| ------------------------- | ---------------------------- | | 200 OK | Project successfully created | | 422 Unprocessable entity | Validation error occurred | | 500 Internal server error | Internal server error | @@ -107,7 +107,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|------------------------------| +| ------------------------- | ---------------------------- | | 200 OK | Project successfully created | | 500 Internal server error | Internal server error | @@ -122,29 +122,29 @@ file system and any un-pushed/un-deployed(terminology in Mission Portal UI) chan **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **repositoryUrl** *(string)* +- **repositoryUrl** _(string)_ Git repository URL. Project will be synchronized with this repository. Supported protocols: `http`, `https`, `ssh` , `git`. Required. Git repository URL example: https://github.com/username/repository.git -* **branch** *(string)* +- **branch** _(string)_ Repository branch. -* **name** *(string)* +- **name** _(string)_ Project name. -* **authenticationType** *(string)* +- **authenticationType** _(string)_ Authentication type that will be used to get access to the repository. Allowed values: `password`, `private_key`. -* **username** *(string)* +- **username** _(string)_ Username for authentication to the repository. Required when authentication type is `password`. -* **password** *(string)* +- **password** _(string)_ Password for authentication to the repository. Required when authentication type is `password`. -* **sshPrivateKey** *(string)* +- **sshPrivateKey** _(string)_ SSH private key for authentication to the repository. Required when authentication type is `private_key` and `sshKeyId` is not set. -* **sshKeyId** *(integer)* +- **sshKeyId** _(integer)_ Generated SSH private key ID by [SSH keys API][SSH keys API#Generate SSH key] for authentication to the repository. Required when authentication type is `private_key` and `sshPrivateKey` is not set. @@ -173,7 +173,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|------------------------------| +| ------------------------- | ---------------------------- | | 204 No content | Project successfully updated | | 404 Not found | Project not found | | 422 Unprocessable entity | Validation error occurred | @@ -187,7 +187,7 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. **Example request (curl):** @@ -223,7 +223,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -236,9 +236,9 @@ HTTP 200 OK **Parameters:** -* **skip** *(integer)* +- **skip** _(integer)_ Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* +- **limit** _(integer)_ Limit the number of results in the query. Optional parameter. **Example request (curl):** @@ -294,7 +294,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -307,7 +307,7 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. **Example request (curl):** @@ -327,7 +327,7 @@ HTTP 204 No content **Responses:** | HTTP response code | Description | -|---------------------------|------------------------------| +| ------------------------- | ---------------------------- | | 204 No content | Project successfully deleted | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -340,9 +340,9 @@ HTTP 204 No content **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **action** *(string)* +- **action** _(string)_ Action. Allowed actions: - `push` - pushes local changes to the upstream repository - `rebase` - rebases local changes from the upstream @@ -370,12 +370,12 @@ HTTP 204 No content **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------| +| ------------------------- | --------------------------- | | 204 No content | Project successfully synced | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | -### Refresh project +### Refresh project Fetch upstream repository and return the current state. @@ -385,7 +385,7 @@ Fetch upstream repository and return the current state. **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. **Example request (curl):** @@ -407,9 +407,10 @@ HTTP 200 OK ] } ``` + **Output:** -* **status** +- **status** Project's status. Possible values: - `ok` - project is up-to-date - `behind` - there are changes in upstream which are not pulled @@ -419,7 +420,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -432,7 +433,7 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. **Example request (curl):** @@ -493,7 +494,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -506,11 +507,11 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **module** *(string)* +- **module** _(string)_ Module's name. Required. -* **version** *(string)* +- **version** _(string)_ Module's version. Required. **Example request (curl):** @@ -535,7 +536,7 @@ HTTP 201 Created **Responses:** | HTTP response code | Description | -|---------------------------|---------------------------| +| ------------------------- | ------------------------- | | 201 Created | Module successfully added | | 404 Not found | Project not found | | 422 Unprocessable entity | Validation error occurred | @@ -549,9 +550,9 @@ HTTP 201 Created **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **module** *(string)* +- **module** _(string)_ Module's name. Required. **Example request (curl):** @@ -571,7 +572,7 @@ HTTP 204 No content **Responses:** | HTTP response code | Description | -|---------------------------|------------------------------------------| +| ------------------------- | ---------------------------------------- | | 204 No content | Module successfully deleted from project | | 404 Not found | Project not found | | 500 Internal server error | Internal server error | @@ -584,11 +585,11 @@ HTTP 204 No content **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **module** *(string)* +- **module** _(string)_ Module's name. Required. -* **version** *(string)* +- **version** _(string)_ Module's version. Required. **Example request (curl):** @@ -613,7 +614,7 @@ HTTP No content **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------| +| ------------------------- | --------------------------- | | 204 No content | Module successfully updated | | 404 Not found | Project not found | | 422 Unprocessable entity | Validation error occurred | @@ -627,17 +628,17 @@ HTTP No content **Parameters:** -* **sortColumn** *(string)* +- **sortColumn** _(string)_ Column name on which to sort results. Default value: `name`. Optional parameter. -* **sortDescending** *(boolean)* +- **sortDescending** _(boolean)_ Sorting order. Optional parameter. Default value: `false`. Optional parameter. -* **searchQuery** *(string)* +- **searchQuery** _(string)_ Search query for a full-text search based on modules name and description. Optional parameter. -* **tag** *(string)* +- **tag** _(string)_ Filter modules by tag. Optional parameter. -* **skip** *(integer)* +- **skip** _(integer)_ Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* +- **limit** _(integer)_ Limit the number of results in the query. Optional parameter. **Example request (curl):** @@ -699,7 +700,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 500 Internal server error | Internal server error | @@ -728,7 +729,7 @@ curl --user : \ **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------------| +| ------------------------- | --------------------------------- | | 204 No content | Modules list successfully updated | | 500 Internal server error | Internal server error | @@ -740,7 +741,7 @@ curl --user : \ **Parameters:** -* **name** *(string)* +- **name** _(string)_ Module name. Default value: `name`. Required. **Example request (curl):** @@ -791,7 +792,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Module not found | | 500 Internal server error | Internal server error | @@ -805,9 +806,9 @@ HTTP 200 OK **Parameters:** sortColumn searchQuery tag -* **name** *(string)* +- **name** _(string)_ Module name. Required. -* **version** *(string)* +- **version** _(string)_ Module version. Required. **Example request (curl):** @@ -858,7 +859,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------| +| ------------------------- | --------------------- | | 200 Ok | Successful response | | 404 Not found | Module not found | | 500 Internal server error | Internal server error | @@ -871,9 +872,9 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **name** *(string)* +- **name** _(string)_ Module name. Required. **Example request (curl):** @@ -926,7 +927,7 @@ HTTP 200 OK **Output:** -* **input_spec** *(JSON array of objects)* +- **input_spec** _(JSON array of objects)_ Input specification represented as an JSON array of objects. Each object specifies one input entry for the module. To discover more information about these fields, @@ -935,7 +936,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------| +| ------------------------- | --------------------------- | | 200 Ok | Successful response | | 404 Not found | Project or module not found | | 500 Internal server error | Internal server error | @@ -948,21 +949,22 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Project's ID. Required. -* **name** *(string)* +- **name** _(string)_ Module name. Required. **Request body:** - Request body should contain input specification from the [Get input data request][Build API#Get CFEngine Build module input data] - where each object should have a `response` property with the data. +Request body should contain input specification from the [Get input data request][Build API#Get CFEngine Build module input data] +where each object should have a `response` property with the data. + +**response** might be: - **response** might be: - * an JSON array of objects, in case of list input type with string subtypes. +- an JSON array of objects, in case of list input type with string subtypes. An object should be a key-value pair where a key is from input specification and value should be a string. - * string, in case of string input type +- string, in case of string input type **Example request (curl):** @@ -1016,7 +1018,7 @@ HTTP 200 OK **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------| +| ------------------------- | --------------------------- | | 200 Ok | Successful response | | 404 Not found | Project or module not found | | 500 Internal server error | Internal server error | diff --git a/content/api/enterprise-api-ref/changes.markdown b/content/api/enterprise-api-ref/changes.markdown index 2278e26e8..ab450e496 100644 --- a/content/api/enterprise-api-ref/changes.markdown +++ b/content/api/enterprise-api-ref/changes.markdown @@ -15,30 +15,30 @@ Count changes performed by CFEngine to the infrastructure. Count can be narrowed **Note:** In the environments with extensive policy and large number of clients it is recommended to narrow down the results as much as possible to achieve more precise results and faster response times. This can be done by specifying filtering parameters listed below. -* **from** *(integer)* - Include changes performed within interval. Starting **from** unix timestamp. If not specified default value is last 24 hours. -* **to** *(integer)* - Include changes performed within interval. Ending at **to** unix timestamp. If not specified default value is NOW. -* **include** *(array)* - Include only nodes that have set specified context (cfengine class). Defaults to include all nodes. -* **exclude** *(array)* - Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes. -* **hostkey** *(string)* - Search results for nodes matching specified unique hostkey. -* **stackpath** *(string)* - Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisetype** *(string)* - Search results matching specified promise type - such as *commands*, *processes* etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisehandle** *(string)* - Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **bundlename** *(string)* - Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **policyfile** *(string)* - Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **logmessages** *(string)* - Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisees** *(string)* - Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **from** _(integer)_ + Include changes performed within interval. Starting **from** unix timestamp. If not specified default value is last 24 hours. +- **to** _(integer)_ + Include changes performed within interval. Ending at **to** unix timestamp. If not specified default value is NOW. +- **include** _(array)_ + Include only nodes that have set specified context (cfengine class). Defaults to include all nodes. +- **exclude** _(array)_ + Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes. +- **hostkey** _(string)_ + Search results for nodes matching specified unique hostkey. +- **stackpath** _(string)_ + Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisetype** _(string)_ + Search results matching specified promise type - such as _commands_, _processes_ etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisehandle** _(string)_ + Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **bundlename** _(string)_ + Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **policyfile** _(string)_ + Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **logmessages** _(string)_ + Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisees** _(string)_ + Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. **Example response:** @@ -50,8 +50,8 @@ Count changes performed by CFEngine to the infrastructure. Count can be narrowed **Output:** -* **count** - Total count of changes performed by cf-agent that match specified filtering criteria. +- **count** + Total count of changes performed by cf-agent that match specified filtering criteria. **Example usage:** `Example: Count changes` @@ -67,36 +67,36 @@ List changes performed by CFEngine to the infrastructure. List can be narrowed d **Parameters:** -* **from** *(integer)* - Include changes performed within interval. Starting **from** unix timestamp. If not specified default value is last 24 hours. -* **to** *(integer)* - Include changes performed within interval. Ending at **to** unix timestamp. If not specified default value is NOW. -* **include** *(array)* - Include only nodes that have set specified context (cfengine class). Defaults to include all nodes. -* **exclude** *(array)* - Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes. -* **hostkey** *(string)* - Search results for nodes matching specified unique hostkey. -* **stackpath** *(string)* - Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisetype** *(string)* - Search results matching specified promise type - such as *commands*, *processes* etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisehandle** *(string)* - Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **bundlename** *(string)* - Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **policyfile** *(string)* - Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **logmessages** *(string)* - Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **promisees** *(string)* - Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. -* **sort** *(string)* - Sort results by specified direction and attribute. By default sort direction is ascending, to sort as descending add '-' before attribute name. Result can be sorted by all returned fields. If not specified results are not sorted. Examples: *sort=bundlename* - sort ascending by bundlename, *sort=-promisehandle* - sort descending by promise handle. -* **count** *(integer)* - Page size. Default 50 items. -* **page** *(integer)* - Page number. Default 1st page. +- **from** _(integer)_ + Include changes performed within interval. Starting **from** unix timestamp. If not specified default value is last 24 hours. +- **to** _(integer)_ + Include changes performed within interval. Ending at **to** unix timestamp. If not specified default value is NOW. +- **include** _(array)_ + Include only nodes that have set specified context (cfengine class). Defaults to include all nodes. +- **exclude** _(array)_ + Exclude only nodes that have set specified context (cfengine class). Defaults to exclude no nodes. +- **hostkey** _(string)_ + Search results for nodes matching specified unique hostkey. +- **stackpath** _(string)_ + Search results matching specified stack path which is execution stack of the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisetype** _(string)_ + Search results matching specified promise type - such as _commands_, _processes_ etc. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisehandle** _(string)_ + Search results matching specified promise handle. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **bundlename** _(string)_ + Search results matching specified bundle name. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **policyfile** _(string)_ + Search results matching specified path for policy file where promise is defined. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **logmessages** _(string)_ + Search results matching any of the messages logged for the promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **promisees** _(string)_ + Search results matching any of the promisees specified for promise. Search is key insensitive. Additionally filter supports ending wildcard which can be enabled with placing '%' sign at the end. +- **sort** _(string)_ + Sort results by specified direction and attribute. By default sort direction is ascending, to sort as descending add '-' before attribute name. Result can be sorted by all returned fields. If not specified results are not sorted. Examples: _sort=bundlename_ - sort ascending by bundlename, _sort=-promisehandle_ - sort descending by promise handle. +- **count** _(integer)_ + Page size. Default 50 items. +- **page** _(integer)_ + Page number. Default 1st page. **Example response:** @@ -147,33 +147,33 @@ List changes performed by CFEngine to the infrastructure. List can be narrowed d **Output:** -* **total** - Total number of results. -* **next** - Link for fetching next page. Set to NULL if current page is last. -* **previous** - Link for previous page. Set to NULL if the current page if the first. -* **data.bundlename** - [Bundle][Bundles] name where the promise is executed. -* **data.changetime** - Time of performing change by cf-agent to the system. Expressed as UNIT TIMESTAMP. -* **data.hostkey** - Unique host identifier. -* **data.hostname** - Host name locally detected on the host, configurable as `hostIdentifier` option in [Settings API][Status and settings REST API#Get settings] and Mission Portal settings UI. -* **data.logmessages** - List of 5 last messages generated during promise execution. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. -* **data.policyfile** - Path to the file where the promise is located in. -* **data.promisees** - List of [promisees][Promises] defined for the promise. -* **data.promisehandle** - A unique id-tag string for referring promise. -* **data.promiser** - Object affected by a promise. -* **data.promisetype** - [Type][Promise types] of the promise. -* **data.stackpath** - Call stack of the promise. +- **total** + Total number of results. +- **next** + Link for fetching next page. Set to NULL if current page is last. +- **previous** + Link for previous page. Set to NULL if the current page if the first. +- **data.bundlename** + [Bundle][Bundles] name where the promise is executed. +- **data.changetime** + Time of performing change by cf-agent to the system. Expressed as UNIT TIMESTAMP. +- **data.hostkey** + Unique host identifier. +- **data.hostname** + Host name locally detected on the host, configurable as `hostIdentifier` option in [Settings API][Status and settings REST API#Get settings] and Mission Portal settings UI. +- **data.logmessages** + List of 5 last messages generated during promise execution. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. +- **data.policyfile** + Path to the file where the promise is located in. +- **data.promisees** + List of [promisees][Promises] defined for the promise. +- **data.promisehandle** + A unique id-tag string for referring promise. +- **data.promiser** + Object affected by a promise. +- **data.promisetype** + [Type][Promise types] of the promise. +- **data.stackpath** + Call stack of the promise. **Example usage:** `Example: Show vacuum command executions` diff --git a/content/api/enterprise-api-ref/cmdb-api.markdown b/content/api/enterprise-api-ref/cmdb-api.markdown index af14b9488..d7f34c5e6 100644 --- a/content/api/enterprise-api-ref/cmdb-api.markdown +++ b/content/api/enterprise-api-ref/cmdb-api.markdown @@ -15,23 +15,23 @@ You can see a list of stored host-specific configurations **Parameters:** -* **fromEpoch** *(integer)* +- **fromEpoch** _(integer)_ Returns configurations with epoch value greater than set in the filter. Epoch is the sequence number of the latest CMDB change. In every API list request, `cmdb_epoch` will be present in the meta section, which contains the maximum epoch value among selected items. Optional parameter. -* **fromTime** *(timestamp)* +- **fromTime** _(timestamp)_ Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` or `YYYY-mm-dd`. Optional parameter. -* **toTime** *(timestamp)* +- **toTime** _(timestamp)_ Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` or `YYYY-mm-dd`. Optional parameter. -* **skip** *(integer)* +- **skip** _(integer)_ Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* +- **limit** _(integer)_ Limit the number of results in the query. Optional parameter. -* **hostContextInclude** *(array)* +- **hostContextInclude** _(array)_ Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. -* **hostContextExclude** *(array)* +- **hostContextExclude** _(array)_ Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter. **Example request (curl):** @@ -84,13 +84,13 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Example request (curl):** @@ -127,7 +127,7 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. **Example request (curl):** @@ -172,24 +172,24 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Request body parameters:** -* **value** *(string|array)* +- **value** _(string|array)_ Variable value, can be array or text. Classes do not support values. -* **comment** *(string)* +- **comment** _(string)_ Variables or classes description. Optional parameter. -* **tags** *(array)* +- **tags** _(array)_ Variables or classes tags. Optional parameter. **Example request (curl):** @@ -220,9 +220,9 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **classes** *(JSON object)* +- **classes** _(JSON object)_ The format is a JSON object where the key is class name and value is another JSON object with optionals `comment` and `tags` property. Example: @@ -239,7 +239,7 @@ HTTP 200 Ok } ``` -* **variables** *(JSON object)* +- **variables** _(JSON object)_ The format is a JSON object where the key is variable name and value is another JSON object with a required `value` property and optionals `comment` and `tags`. Example: @@ -290,6 +290,7 @@ curl -k --user : \ ``` HTTP 201 Created ``` + ## Update configuration **URI:** https://hub.cfengine.com/api/cmdb/:hostkey/:type/:name/ @@ -298,27 +299,27 @@ HTTP 201 Created **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Request body parameters:** -* **value** *(string|array)* +- **value** _(string|array)_ Variable value, can be array or text. Classes do not support values. -* **comment** *(string)* +- **comment** _(string)_ Variables or classes description. Optional parameter. -* **tags** *(array)* +- **tags** _(array)_ Variables or classes tags. Optional parameter. -* **name** *(string)* +- **name** _(string)_ New name, in case of renaming. Optional parameter. **Example request (curl):** @@ -349,9 +350,9 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **classes** *(JSON object)* +- **classes** _(JSON object)_ The format is a JSON object where the key is class name and value is another JSON object with an optional `comment` property. Example: @@ -372,7 +373,7 @@ If you need to delete all classes from host you need to set null value: If your request body misses classes then the previous value will be preserved. -* **variables** *(JSON object)* +- **variables** _(JSON object)_ The format is a JSON object where the key is variable name and value is another JSON object with a required `value` property and an optional `comment` property. Example: @@ -396,6 +397,7 @@ If you need to delete all variables from host you need to set null value: "variables": null } ``` + If your request body misses variables then the previous value will be preserved. **Example request (curl):** @@ -438,7 +440,7 @@ HTTP 200 Ok **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. **Example request (curl):** @@ -463,13 +465,13 @@ HTTP 204 No Content **Parameters:** -* **hostkey** *(string)* +- **hostkey** _(string)_ Unique host identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Example request (curl):** diff --git a/content/api/enterprise-api-ref/export-import-api.markdown b/content/api/enterprise-api-ref/export-import-api.markdown index e9fefbbbe..1858f3b98 100644 --- a/content/api/enterprise-api-ref/export-import-api.markdown +++ b/content/api/enterprise-api-ref/export-import-api.markdown @@ -73,10 +73,10 @@ HTTP 200 Ok **Output:** -* **id** - Item id. Use this id in export API call. -* **name** - Name of export item. +- **id** + Item id. Use this id in export API call. +- **name** + Name of export item. ## Export @@ -86,15 +86,15 @@ HTTP 200 Ok **Parameters:** -* **item_id** *(array)* - Item id to be exported. - List of item ids you can obtain through [List of items to export][Import & export API#Get available items to export] - call described below. +- **item_id** _(array)_ + Item id to be exported. + List of item ids you can obtain through [List of items to export][Import & export API#Get available items to export] + call described below. -* **encryptionKey** *(string)* - Encryption key to encrypt sensitive data. Please save this key to be able to import the data. -* **exportOnlyUserItems** *(string)* - `true` - export only user items. `false` - export whole system data +- **encryptionKey** _(string)_ + Encryption key to encrypt sensitive data. Please save this key to be able to import the data. +- **exportOnlyUserItems** _(string)_ + `true` - export only user items. `false` - export whole system data **Example request (curl):** @@ -115,10 +115,10 @@ HTTP 200 Ok **Output:** -* **name** - Name of export file. -* **url** - Url of export file. +- **name** + Name of export file. +- **url** + Url of export file. ## Download export file @@ -128,7 +128,7 @@ HTTP 200 Ok **Parameters:** -* **file_name** *(string)* +- **file_name** _(string)_ File name to be downloaded. **Example request (curl):** @@ -150,12 +150,12 @@ Raw file contetnt **Output headers:** -* Cache-Control: must-revalidate, post-check=0, pre-check=0 -* Pragma: public -* Content-Description: File Transfer -* Content-Disposition: attachment; filename="export_12-14-2018_16:04:46.093500.phar" -* Content-Length: 337801 -* Content-Type: application/octet-stream +- Cache-Control: must-revalidate, post-check=0, pre-check=0 +- Pragma: public +- Content-Description: File Transfer +- Content-Disposition: attachment; filename="export_12-14-2018_16:04:46.093500.phar" +- Content-Length: 337801 +- Content-Type: application/octet-stream ## Analyze import file @@ -167,8 +167,8 @@ This API call allows you to see short summary of file content. **Parameters:** -* **file** *(form data file)* - File to be analyzed. +- **file** _(form data file)_ + File to be analyzed. **Example request (curl):** @@ -199,14 +199,14 @@ HTTP 200 Ok **Parameters:** -* **file** *(form data file)* - File to be analyzed. -* **encryptionKey** *(string)* - Encryption key that was set while export. -* **skipDuplicates** *(number)* - Merge conflict strategy: - `1` - skip duplicate items. - `0` - overwrite duplicate items. +- **file** _(form data file)_ + File to be analyzed. +- **encryptionKey** _(string)_ + Encryption key that was set while export. +- **skipDuplicates** _(number)_ + Merge conflict strategy: + `1` - skip duplicate items. + `0` - overwrite duplicate items. **Example request (curl):** diff --git a/content/api/enterprise-api-ref/export-import-compliance-report-api.markdown b/content/api/enterprise-api-ref/export-import-compliance-report-api.markdown index 26b4d3dfe..a2b4061d5 100644 --- a/content/api/enterprise-api-ref/export-import-compliance-report-api.markdown +++ b/content/api/enterprise-api-ref/export-import-compliance-report-api.markdown @@ -79,77 +79,77 @@ HTTP 200 Ok **Parameters:** -* **data** *(json)* - Reports and conditions data to be imported. Data json object should have two nested objects: `reports` and `condtions`: - * **reports** - JSON object where the key is report ID, which will be used to identify if report already exists in the system. - * **id** *(text)* - Report ID - * **type** *(text)* - Report's type. Should be set to `complince` - * **title** *(text)* - Report's title. - * **conditions** *(array)* - Conditions list - * **conditions** - JSON object where the key is condition ID, which will be used to identify if condition already exists in the system. - * **id** *(text)* - Condition ID - * **name** *(text)* - Condition name - * **description** *(text)* - Condition description - * **condition_for** *(text)* - Condition for `passing` or `failing`. - * **type** *(text)* - Condition type. Possible values: `inventory`, `custom`, `fileChanged`, `policy`, `software` - * **rules** *(json object)* - JSON object that define rules. Each type has own set of fields: - * **inventory** - * **attribute** *(text)* - Inventory attribute - * **operator** *(text)* - Operator. Possible values: `matches`, `not_match`, `contains`, `not_contain`, `regex_matches`, `regex_not_match`, `is_not_reported`, `is_reported`, `<`, `>`, `<=`, `>=`, `=`, `!=` - * **value** *(text)* - Value. This field might be skipped in case of `is_reported` or `is_not_reported` operators - * **custom** - * **sql** *(text)* - Custom SQL - * **fileChanged** - * **file-name** *(text)* - File name - * **condition** *(text)* - Condition. Possible values: `matches`, `is` - * **time-period** *(int)* - Changed within the time period (hours). - * **policy** - * **filter-by** *(text)* - Filter by: `Bundlename`, `Promisees`, `Promiser` - * **value** *(text)* - Filter value - * **promise-handle** *(text)* - Promise handle - * **promise-status** *(text)* - Promise status: `KEPT`, `NOTKEPT`, `REPAIRED` - * **software** - * **package-name** *(text)* - Package name - * **condition** *(text)* - Condition: `matches`, `is` - * **architecture** *(text)* - Architecture - * **category** *(text)* - Conditions category - * **severity** *(text)* - Condition severity. Possible values: `low`, `medium`, `high` - * **host_filter** *(text)* - Host filter, should be valid class expression. - -* **overwrite** *(booleans)* - Set true to overwrite existing reports or conditions that belong to you. Default: false - -* **public** *(booleans)* - Set true to make report publicly accessible. Default: false +- **data** _(json)_ + Reports and conditions data to be imported. Data json object should have two nested objects: `reports` and `condtions`: + - **reports** + JSON object where the key is report ID, which will be used to identify if report already exists in the system. + - **id** _(text)_ + Report ID + - **type** _(text)_ + Report's type. Should be set to `complince` + - **title** _(text)_ + Report's title. + - **conditions** _(array)_ + Conditions list + - **conditions** + JSON object where the key is condition ID, which will be used to identify if condition already exists in the system. + - **id** _(text)_ + Condition ID + - **name** _(text)_ + Condition name + - **description** _(text)_ + Condition description + - **condition_for** _(text)_ + Condition for `passing` or `failing`. + - **type** _(text)_ + Condition type. Possible values: `inventory`, `custom`, `fileChanged`, `policy`, `software` + - **rules** _(json object)_ + JSON object that define rules. Each type has own set of fields: + - **inventory** + - **attribute** _(text)_ + Inventory attribute + - **operator** _(text)_ + Operator. Possible values: `matches`, `not_match`, `contains`, `not_contain`, `regex_matches`, `regex_not_match`, `is_not_reported`, `is_reported`, `<`, `>`, `<=`, `>=`, `=`, `!=` + - **value** _(text)_ + Value. This field might be skipped in case of `is_reported` or `is_not_reported` operators + - **custom** + - **sql** _(text)_ + Custom SQL + - **fileChanged** + - **file-name** _(text)_ + File name + - **condition** _(text)_ + Condition. Possible values: `matches`, `is` + - **time-period** _(int)_ + Changed within the time period (hours). + - **policy** + - **filter-by** _(text)_ + Filter by: `Bundlename`, `Promisees`, `Promiser` + - **value** _(text)_ + Filter value + - **promise-handle** _(text)_ + Promise handle + - **promise-status** _(text)_ + Promise status: `KEPT`, `NOTKEPT`, `REPAIRED` + - **software** + - **package-name** _(text)_ + Package name + - **condition** _(text)_ + Condition: `matches`, `is` + - **architecture** _(text)_ + Architecture + - **category** _(text)_ + Conditions category + - **severity** _(text)_ + Condition severity. Possible values: `low`, `medium`, `high` + - **host_filter** _(text)_ + Host filter, should be valid class expression. + +- **overwrite** _(booleans)_ + Set true to overwrite existing reports or conditions that belong to you. Default: false + +- **public** _(booleans)_ + Set true to make report publicly accessible. Default: false **Example request (curl):** @@ -222,12 +222,13 @@ HTTP 200 OK **Output:** -* **processed-conditions** - List of processed conditions where the key is condition ID from the data JSON and the value is internal - ID from the database. -* **processed-reports** - List of processed reports where the key is condition ID from the data JSON and the value is internal - ID from the database. +- **processed-conditions** + List of processed conditions where the key is condition ID from the data JSON and the value is internal + ID from the database. +- **processed-reports** + List of processed reports where the key is condition ID from the data JSON and the value is internal + ID from the database. ## History -* Introduced in CFEngine 3.19.0, 3.18.1 + +- Introduced in CFEngine 3.19.0, 3.18.1 diff --git a/content/api/enterprise-api-ref/federated-reporting-api.markdown b/content/api/enterprise-api-ref/federated-reporting-api.markdown index 96c28654c..2c39d00e0 100644 --- a/content/api/enterprise-api-ref/federated-reporting-api.markdown +++ b/content/api/enterprise-api-ref/federated-reporting-api.markdown @@ -62,8 +62,8 @@ HTTP 200 OK **Parameters:** -* **remote_hub_id** *(number)* - Remote hub id +- **remote_hub_id** _(number)_ + Remote hub id **Example response:** @@ -94,16 +94,16 @@ HTTP 200 OK **Parameters:** -* **ui_name** *(string)* - Remote hub name -* **hostkey** *(string)* - Remote hub hostkey -* **role** *(string)* - Remote hub role. Allowed values: `feeder`, `superhub` -* **target_state** *(string)* - Target state of remote hub. Allowed values: `on`, `paused` -* **transport** *(json)* - Transport data. Emp `{ "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}` +- **ui_name** _(string)_ + Remote hub name +- **hostkey** _(string)_ + Remote hub hostkey +- **role** _(string)_ + Remote hub role. Allowed values: `feeder`, `superhub` +- **target_state** _(string)_ + Target state of remote hub. Allowed values: `on`, `paused` +- **transport** _(json)_ + Transport data. Emp `{ "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}` **Example response:** @@ -119,18 +119,18 @@ HTTP 201 CREATED **Parameters:** -* **remote_hub_id** *(number)* - Remote hub id -* **ui_name** *(string)* - Remote hub name -* **hostkey** *(string)* - Remote hub hostkey -* **role** *(string)* - Remote hub role. Allowed values: `feeder`, `superhub` -* **target_state** *(string)* - Target state of remote hub. Allowed values: `on`, `paused` -* **transport** *(json)* - Transport data. Emp `{ "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}` +- **remote_hub_id** _(number)_ + Remote hub id +- **ui_name** _(string)_ + Remote hub name +- **hostkey** _(string)_ + Remote hub hostkey +- **role** _(string)_ + Remote hub role. Allowed values: `feeder`, `superhub` +- **target_state** _(string)_ + Target state of remote hub. Allowed values: `on`, `paused` +- **transport** _(json)_ + Transport data. Emp `{ "mode": "pull_over_rsync", "ssh_user": "cfdrop", "ssh_host": "172.28.128.5", "ssh_pubkey": "", "ssh_fingerprint": ""}` **Example response:** @@ -146,8 +146,8 @@ HTTP 202 ACCEPTED **Parameters:** -* **remote_hub_id** *(number)* - Remote hub id +- **remote_hub_id** _(number)_ + Remote hub id **Example response:** diff --git a/content/api/enterprise-api-ref/file-changes.markdown b/content/api/enterprise-api-ref/file-changes.markdown index f87bb7c8b..74d21db49 100644 --- a/content/api/enterprise-api-ref/file-changes.markdown +++ b/content/api/enterprise-api-ref/file-changes.markdown @@ -11,10 +11,10 @@ title: File changes API Get file changes statistics by period. -* **fromTime** *(timestamp)* - Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` -* **toTime** *(timestamp)* - Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` +- **fromTime** _(timestamp)_ + Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` +- **toTime** _(timestamp)_ + Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` **Example request (curl):** @@ -81,13 +81,13 @@ curl -k --user : \ **Output:** -* **DIFF** - Contains object with statistics of a change in content (with file diff), the object's key is change date and object's value is a number of changed files. -* **C** - Contains object with statistics of a change in content (based on file hash), the object's key is change date and object's value is a number of changed files. -* **S** - Contains object with statistics of a change in file stats, the object's key is change date and object's value is a number of changed files. -* **labels** - Labels of `DIFF, C, S ` change types. -* **dates** - The array of selected dates. +- **DIFF** + Contains object with statistics of a change in content (with file diff), the object's key is change date and object's value is a number of changed files. +- **C** + Contains object with statistics of a change in content (based on file hash), the object's key is change date and object's value is a number of changed files. +- **S** + Contains object with statistics of a change in file stats, the object's key is change date and object's value is a number of changed files. +- **labels** + Labels of `DIFF, C, S ` change types. +- **dates** + The array of selected dates. diff --git a/content/api/enterprise-api-ref/first-time-setup.markdown b/content/api/enterprise-api-ref/first-time-setup.markdown index f4673d159..b66437875 100644 --- a/content/api/enterprise-api-ref/first-time-setup.markdown +++ b/content/api/enterprise-api-ref/first-time-setup.markdown @@ -46,13 +46,13 @@ HTTP 200 Ok **Output:** -* **is_setup_complete** +- **is_setup_complete** Boolean value indicating whether the system has been set up (true) or not (false) **Responses:** | HTTP response code | Description | -|---------------------------|-------------------------------| +| ------------------------- | ----------------------------- | | 200 OK | Setup status check successful | | 500 Internal server error | Internal server error | @@ -67,7 +67,7 @@ This endpoint returns a session ID required for the setup complete API request. **Parameters:** -* **code** *(string)* +- **code** _(string)_ The setup code provided during system initialization **Example request (curl):** @@ -90,18 +90,18 @@ HTTP 200 Ok **Output:** -* **session_id** +- **session_id** The session ID to be used in the setup complete API request -* **valid** +- **valid** Boolean value indicating whether the provided code is valid **Responses:** -| HTTP response code | Description | -|---------------------------|-------------------------------| -| 200 OK | Code validation successful | -| 400 Bad request | Invalid or missing code | -| 500 Internal server error | Internal server error | +| HTTP response code | Description | +| ------------------------- | -------------------------- | +| 200 OK | Code validation successful | +| 400 Bad request | Invalid or missing code | +| 500 Internal server error | Internal server error | ## Complete setup @@ -114,16 +114,16 @@ It requires a valid session ID obtained from the code validation step. **Headers:** -* **Cf-Setup-Session-Id** *(string)* +- **Cf-Setup-Session-Id** _(string)_ Session ID obtained from the code validation step **Parameters:** -* **username** *(string)* +- **username** _(string)_ Alphanumeric username for the administrator account -* **password** *(string)* +- **password** _(string)_ Password for the administrator account -* **email** *(string)* +- **email** _(string)_ Email address for the administrator account **Example request (curl):** @@ -147,9 +147,9 @@ HTTP 201 Created **Responses:** -| HTTP response code | Description | -|---------------------------|---------------------------------------------------| -| 201 Created | Setup successfully completed | -| 406 Not Acceptable | Invalid session ID | -| 400 Bad request | Missing or invalid parameters | -| 500 Internal server error | Internal server error | +| HTTP response code | Description | +| ------------------------- | ----------------------------- | +| 201 Created | Setup successfully completed | +| 406 Not Acceptable | Invalid session ID | +| 400 Bad request | Missing or invalid parameters | +| 500 Internal server error | Internal server error | diff --git a/content/api/enterprise-api-ref/health-diagnostic.markdown b/content/api/enterprise-api-ref/health-diagnostic.markdown index 7aa2b9e14..4358d2271 100644 --- a/content/api/enterprise-api-ref/health-diagnostic.markdown +++ b/content/api/enterprise-api-ref/health-diagnostic.markdown @@ -57,24 +57,25 @@ API performance depend on the query result size, to achieve fastest results cons **Parameters:** -* **report_id** *(string)* - Report id. - List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] -* **sortColumn** *(string)* - Column name on which to sort results. Optional parameter. -* **sortDescending** *(boolean)* - Sorting order. Optional parameter. -* **skip** *(integer)* - Number of results to skip for the processed - query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* - Limit the number of results in the query. -* **hostContextInclude** *(array)* - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. -* **hostContextExclude** *(array)* - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. +- **report_id** _(string)_ + Report id. + List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] +- **sortColumn** _(string)_ + Column name on which to sort results. Optional parameter. +- **sortDescending** _(boolean)_ + Sorting order. Optional parameter. +- **skip** _(integer)_ + Number of results to skip for the processed + query. The Mission Portal uses this for pagination. Optional parameter. +- **limit** _(integer)_ + Limit the number of results in the query. +- **hostContextInclude** _(array)_ + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. +- **hostContextExclude** _(array)_ + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. **CURL Request Example:** + ``` curl -k --user : -X POST \ https://hub.cfengine.com/api/health-diagnostic/report/agentNotRunRecently \ @@ -142,15 +143,16 @@ curl -k --user : -X POST \ **Parameters** -* **report_id** *(string)* - Report id. - List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] -* **offset** *(integer)* - Number of results to skip for the processed query. -* **limit** *(integer)* - Limit the number of results in the query. +- **report_id** _(string)_ + Report id. + List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] +- **offset** _(integer)_ + Number of results to skip for the processed query. +- **limit** _(integer)_ + Limit the number of results in the query. **CURL Request Example:** + ``` curl -k --user : -X GET \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected?limit=3&offset=0 @@ -229,13 +231,14 @@ curl -k --user : -X GET \ **Parameters** -* **report_id** *(string)* - Report id. - List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] -* **hosts** *(array)* - Array of host keys to dismiss +- **report_id** _(string)_ + Report id. + List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] +- **hosts** _(array)_ + Array of host keys to dismiss **CURL Request Example:** + ``` curl -k --user admin:admin -X POST \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected \ @@ -257,13 +260,14 @@ HTTP 201 CREATED **Parameters** -* **report_id** *(string)* - Report id. - List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] -* **hosts** *(array)* - Array of host keys to remove from dismissed list +- **report_id** _(string)_ + Report id. + List of report ids you can obtain through [List of health diagnostic report categories][Health diagnostic API#List of health diagnostic report categories] +- **hosts** _(array)_ + Array of host keys to remove from dismissed list **CURL Request Example:** + ``` curl -k --user admin:admin -X POST \ https://hub.cfengine.com/api/health-diagnostic/dismiss/notRecentlyCollected \ diff --git a/content/api/enterprise-api-ref/host.markdown b/content/api/enterprise-api-ref/host.markdown index 01c4357a8..f4de515fb 100644 --- a/content/api/enterprise-api-ref/host.markdown +++ b/content/api/enterprise-api-ref/host.markdown @@ -13,16 +13,16 @@ Host API allows to access host specific information. **Parameters:** -* **context-include** *(comma delimited string of regular expression - strings)* - Includes hosts having context matching the expression. -* **context-exclude** *(comma delimited string of regular expression - strings)* - Excludes hosts having context matching the expression. -* **page** *(integer)* - Number of the page with results. By default 1. -* **count** *(integer)* - Size of the page. By default 50 results. +- **context-include** _(comma delimited string of regular expression + strings)_ + Includes hosts having context matching the expression. +- **context-exclude** _(comma delimited string of regular expression + strings)_ + Excludes hosts having context matching the expression. +- **page** _(integer)_ + Number of the page with results. By default 1. +- **count** _(integer)_ + Size of the page. By default 50 results. **Example response:** @@ -55,16 +55,16 @@ Host API allows to access host specific information. **Output:** -* **id** - Unique host identifier. -* **hostname** - Host name. Can be reconfigured globally to represent variable set in the policy using **hostIdentifier** [setting][Status and settings REST API#Update settings]. -* **ip** - IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server. -* **lastreport** - Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP. -* **firstseen** - Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP. +- **id** + Unique host identifier. +- **hostname** + Host name. Can be reconfigured globally to represent variable set in the policy using **hostIdentifier** [setting][Status and settings REST API#Update settings]. +- **ip** + IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server. +- **lastreport** + Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP. +- **firstseen** + Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP. **Example usage:** `Example: Listing hosts with a given context`, `Example: Looking up hosts by hostname`, `Example: Looking up hosts by IP` @@ -98,16 +98,16 @@ Host API allows to access host specific information. **Output:** -* **id** - Unique host identifier. -* **hostname** - Host name. Can be reconfigured globally to represent variable set in the policy using **hostIdentifier** [setting][Status and settings REST API#Update settings]. -* **ip** - IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server. -* **lastreport** - Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP. -* **firstseen** - Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP. +- **id** + Unique host identifier. +- **hostname** + Host name. Can be reconfigured globally to represent variable set in the policy using **hostIdentifier** [setting][Status and settings REST API#Update settings]. +- **ip** + IP address of the host. If host have multiple network interfaces, IP belongs to the interface that is used to communicate with policy server. +- **lastreport** + Time of receiving last report from the client, successfully. Represented as UNIX TIMESTAMP. +- **firstseen** + Time of receiving the first status report from the client. It is equivalent to the time when the client have been bootstrapped to the server for the first time. Represented as UNIX TIMESTAMP. ## Remove host from the hub @@ -124,16 +124,16 @@ Other response codes are also possible (access denied, server error, etc.). Only users with the admin role are allowed to delete hosts. Reporting data associated with the host is immediately purged. -This includes SQL tables like `agentstatus`, `hosts`, `contexts`, `variables`, etc. +This includes SQL tables like `agentstatus`, `hosts`, `contexts`, `variables`, etc. In order to completely delete the host, a deletion job is scheduled by adding the host to the internal table `KeysPendingForDeletion`. To see what hosts are pending deletion, run the query `SELECT HostKey FROM KeysPendingForDeletion;` against the `cfsettings` database. After 5-10 minutes (one reporting iteration based on the [hub schedule][cf-hub#hub_schedule]), the main thread of cf-hub will pick up the deletion job. The hostkey is then removed from: - * "Last seen" database, which contains network connection info (`/var/cfengine/state/cf_lastseen.lmdb`). - * Public key directory, containing cryptographic keys exchaned during bootstrap (`/var/cfengine/ppkeys`). - * The previously mentioned `KeysPendingForDeletion` table. +- "Last seen" database, which contains network connection info (`/var/cfengine/state/cf_lastseen.lmdb`). +- Public key directory, containing cryptographic keys exchaned during bootstrap (`/var/cfengine/ppkeys`). +- The previously mentioned `KeysPendingForDeletion` table. Note: There is a record of the host retained that includes the time when the host was deleted and this record also prevents further collection from this host identity. @@ -147,13 +147,13 @@ Note: There is a record of the host retained that includes the time when the hos **Parameters:** -* **context-include** *(comma delimited string of regular expression strings)* -* **format** *(string)* - Output format. Default value is `json`. Allowed values: `json`, `yaml`. -* **withInventory** *(boolean)* - Include inventory data to the API response. Default value is `false`. Allowed values: `true`, `false` -* **inventoryFile** *(boolean)* - Make hosts' children values objects which aligns with Ansible inventory that is sourced from a file (so this format is appropriate for caching responses), by default when `inventoryFile` is `false`, the output format aligns with Ansible inventory sourced from a script. Default value is `false`. Allowed values: `true`, `false` +- **context-include** _(comma delimited string of regular expression strings)_ +- **format** _(string)_ + Output format. Default value is `json`. Allowed values: `json`, `yaml`. +- **withInventory** _(boolean)_ + Include inventory data to the API response. Default value is `false`. Allowed values: `true`, `false` +- **inventoryFile** _(boolean)_ + Make hosts' children values objects which aligns with Ansible inventory that is sourced from a file (so this format is appropriate for caching responses), by default when `inventoryFile` is `false`, the output format aligns with Ansible inventory sourced from a script. Default value is `false`. Allowed values: `true`, `false` **CURL unfiltered request example** @@ -258,17 +258,19 @@ curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/by-class?wit **Parameters:** -* **skip** *(integer)* +- **skip** _(integer)_ Number of results to skip for the processed query. Optional parameter. -* **limit** *(integer)* +- **limit** _(integer)_ Limit the number of results in the query. No limit when parameter is not set. Optional parameter. **Example request (curl):** + ``` curl -k --user admin:admin -X GET https://hub.example.com/api/hosts/deleted ``` + **Example response:** ``` @@ -307,15 +309,17 @@ Note: to be able to perform this action related RBAC rule (alias `hosts-undelete **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------| +| ------------------------- | -------------------------- | | 200 OK | Host is found and restored | | 404 NOT FOUND | Host is not found | | 500 Internal server error | Internal server error | **Example request (curl):** + ``` curl -k --user : -X POST https://hub.example.com/api/hosts/restore-deleted/SHA=2123f85b38189008ae12be159fb961584dda1249c94efed43fec2c70f233975d ``` + **Example response:** ``` @@ -335,15 +339,17 @@ Note: to be able to perform this action related RBAC rule (alias `hosts-delete-p **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------------------------| +| ------------------------- | --------------------------------------------- | | 200 OK | Deleted host is found and removed permanently | | 404 NOT FOUND | Host is not found | | 500 Internal server error | Internal server error | **Example request (curl):** + ``` curl -k --user : -X DELETE https://hub.example.com/api/hosts/delete-permanently/SHA=2123f85b38189008ae12be159fb961584dda1249c94efed43fec2c70f233975d ``` + **Example response:** ``` @@ -401,14 +407,14 @@ Note: Collecting monitoring data by default is disabled. **Output:** -* **id** - Unique vital identifier. -* **timestamp** - Last measurement time. Represented as UNIX TIMESTAMP. -* **description** - Vital short description. -* **units** - Units for the samples. +- **id** + Unique vital identifier. +- **timestamp** + Last measurement time. Represented as UNIX TIMESTAMP. +- **description** + Vital short description. +- **units** + Units for the samples. **Example usage:** `Example: Listing available vital signs for a host` @@ -420,10 +426,10 @@ Note: Collecting monitoring data by default is disabled. **Parameters:** -* **from** *(integer)* - Timestamp marking the start of the interval for which to fetch data. Data is only available going back one week. -* **to** *(integer)* - End of data interval to be fetched. +- **from** _(integer)_ + Timestamp marking the start of the interval for which to fetch data. Data is only available going back one week. +- **to** _(integer)_ + End of data interval to be fetched. **Example response:** @@ -462,16 +468,16 @@ Note: Collecting monitoring data by default is disabled. **Output**: -* **id** - ID of vital sign. -* **description** - Description of vital sign. -* **units** - Measurement unit of vital sign. -* **timestamp** - Timestamp of the last received data point. -* **values** - Vital sign data. *(array of [ t, y ], where t is the sample timestamp)* +- **id** + ID of vital sign. +- **description** + Description of vital sign. +- **units** + Measurement unit of vital sign. +- **timestamp** + Timestamp of the last received data point. +- **values** + Vital sign data. _(array of [ t, y ], where t is the sample timestamp)_ **Example usage:** `Example: Retrieving vital sign data` @@ -483,17 +489,19 @@ Note: Collecting monitoring data by default is disabled. **Parameters:** -* **from** *(string)* - Timestamp marking the start of the interval for which to fetch data. `Emp: 2017-11-28` -* **to** *(string)* - End of data interval to be fetched. `Emp: 2017-12-28` -* **period** *(string)* - Group data by period. Allowed values: `day, week, month, year`. +- **from** _(string)_ + Timestamp marking the start of the interval for which to fetch data. `Emp: 2017-11-28` +- **to** _(string)_ + End of data interval to be fetched. `Emp: 2017-12-28` +- **period** _(string)_ + Group data by period. Allowed values: `day, week, month, year`. **Example request (curl):** + ``` curl -k --user admin:admin -X POST https://hub.cfengine.com/api/host-count -H 'content-type: application/json' -d '{"period": "month", "from": "2017-11-28", "to" : "2017-12-06"}' ``` + **Example response:** ``` @@ -515,13 +523,13 @@ HTTP 200 Ok **Output**: -* **period** - Period of grouping the data. Allowed values: `day, week, month, year`. -* **date** - The date of statistic. -* **count** - The bootstrapped hosts to the hub count. +- **period** + Period of grouping the data. Allowed values: `day, week, month, year`. +- **date** + The date of statistic. +- **count** + The bootstrapped hosts to the hub count. ## History -* `inventoryFile=true` parameter added in CFEngine 3.19.0, 3.18.1 +- `inventoryFile=true` parameter added in CFEngine 3.19.0, 3.18.1 diff --git a/content/api/enterprise-api-ref/inventory.markdown b/content/api/enterprise-api-ref/inventory.markdown index 8c2332262..474796ca7 100644 --- a/content/api/enterprise-api-ref/inventory.markdown +++ b/content/api/enterprise-api-ref/inventory.markdown @@ -2,6 +2,7 @@ layout: default title: Inventory API --- + Inventory API allows to access inventory reports and attributes dictionary. ## Inventory reports @@ -12,68 +13,68 @@ Inventory API allows to access inventory reports and attributes dictionary. **Parameters:** -* **select** *(array)* - Fields for selecting. Required parameter. +- **select** _(array)_ + Fields for selecting. Required parameter. - List of fields name you can obtain through [List of inventory attributes][Inventory API#List of inventory attributes] - call described below. Extra attributes are `hostkey` for selecting host key - and `resultCount` for selecting rows count. + List of fields name you can obtain through [List of inventory attributes][Inventory API#List of inventory attributes] + call described below. Extra attributes are `hostkey` for selecting host key + and `resultCount` for selecting rows count. -* **filter** *(json object)* Optionally filter data. You can use array values for multiple filter, the logic will be AND. Format is +- **filter** _(json object)_ Optionally filter data. You can use array values for multiple filter, the logic will be AND. Format is - ``` - { - "Attribute name":{ - "operator":["value","value1"], - "operator2":"value2", - "operator4":"value2" - } + ``` + { + "Attribute name":{ + "operator":["value","value1"], + "operator2":"value2", + "operator4":"value2" } - ``` - - **Operators:** - - For filtering you can use the operators below: - - |Operator | - |-----------------| - | < | - | > | - | = | - | != | - | <= | - | >= | - | matches | - | not_match | - | contains | - | not_contain | - | regex_matches | - | regex_not_match | - | is_reported | - | is_not_reported | - -* **sort** *(string)* - Field name for sorting with "-" for DESC order. Optional parameter. -* **start** *(integer)* - Number of results to start from. Optional parameter. -* **limit** *(integer)* - Limit the number of results in the query. Default value is 1000, max value is 10000. -* **hostContextExclude** *(array)* - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. -* **hostContextInclude** *(array)* - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter. -* **hostFilter** *(json object)* Optional parameter. - * **includes** *(json object)* Optional parameter. - Object that specifies hosts to be included. - * **includeAdditionally** *(boolean)* Default: `false` - Defines if hosts will be added to the results returned by inventory filters or class filters. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` - - * **excludes** *(json object)* Optional parameter. - Object that specifies hosts to be excluded. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` + } + ``` + + **Operators:** + + For filtering you can use the operators below: + + | Operator | + | --------------- | + | < | + | > | + | = | + | != | + | <= | + | >= | + | matches | + | not_match | + | contains | + | not_contain | + | regex_matches | + | regex_not_match | + | is_reported | + | is_not_reported | + +- **sort** _(string)_ + Field name for sorting with "-" for DESC order. Optional parameter. +- **start** _(integer)_ + Number of results to start from. Optional parameter. +- **limit** _(integer)_ + Limit the number of results in the query. Default value is 1000, max value is 10000. +- **hostContextExclude** _(array)_ + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. +- **hostContextInclude** _(array)_ + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. Optional parameter. +- **hostFilter** _(json object)_ Optional parameter. + - **includes** _(json object)_ Optional parameter. + Object that specifies hosts to be included. + - **includeAdditionally** _(boolean)_ Default: `false` + Defines if hosts will be added to the results returned by inventory filters or class filters. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` + + - **excludes** _(json object)_ Optional parameter. + Object that specifies hosts to be excluded. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` ``` curl -k --user : \ @@ -256,9 +257,11 @@ As you can see, despite the OS filter should return zero hosts, we had one addit Shows list of all inventory attributes available in the system. See more details: -* [Custom inventory][Custom inventory] + +- [Custom inventory][Custom inventory] **CURL request example** + ``` curl -k --user admin:admin -X GET https://hub.cfengine.com/api/inventory/attributes-dictionary ``` @@ -299,17 +302,18 @@ Only `readonly - 0` attribute can be edited **Parameters:** -* **id** *(integer)* - Attribute Id -* **category** *(string)* - Category of attribute -* **type** *(string)* - Attribute's type. Allowed values: int, real, slist, string -* **convert_function** *(string)* - Convert Function. - Emp.: `cf_clearSlist` - to transform string like `{"1", "2"}` to `1, 2` +- **id** _(integer)_ + Attribute Id +- **category** _(string)_ + Category of attribute +- **type** _(string)_ + Attribute's type. Allowed values: int, real, slist, string +- **convert_function** _(string)_ + Convert Function. + Emp.: `cf_clearSlist` - to transform string like `{"1", "2"}` to `1, 2` **CURL request example** + ``` curl -k --user admin:admin -X PATCH https://hub.cfengine.com/api/inventory/attributes-dictionary/260 -H 'content-type: application/json' -d '{ "category":"Hardware", diff --git a/content/api/enterprise-api-ref/ldap-api.markdown b/content/api/enterprise-api-ref/ldap-api.markdown index da85e15c3..f2920ece3 100644 --- a/content/api/enterprise-api-ref/ldap-api.markdown +++ b/content/api/enterprise-api-ref/ldap-api.markdown @@ -13,10 +13,10 @@ LDAP authentication API allows to check ldap user credentials and change LDAP se **Parameters:** -* **username** *(string)* - Username from LDAP -* **password** *(string)* - User password +- **username** _(string)_ + Username from LDAP +- **password** _(string)_ + User password **Example response:** @@ -36,8 +36,8 @@ HTTP 200 Ok **Headers:** -* **Authorization: api_token** *(string)* - Set token to access api. To get the token please look at - ```/var/cfengine/httpd/htdocs/ldap/config/settings.php``` +- **Authorization: api_token** _(string)_ + Set token to access api. To get the token please look at - `/var/cfengine/httpd/htdocs/ldap/config/settings.php` **Example response:** @@ -61,26 +61,26 @@ HTTP 200 Ok **Output:** -* **domain_controller** - The domain controllers option is server name located on your network that serve Active Directory. -* **base_dn** - The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org. -* **login_attribute** - Login attribute like cn or uid -* **group_attribute** - Group attribute (e.g. memberOf in Active Directory). Required for [LDAP roles syncing][Settings#LDAP groups syncing] with internal roles. -* **port** - The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636). -* **use_ssl** - Use ssl for connection -* **use_tls** - Use tls for connection -* **timeout** - The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server. -* **admin_username** - LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com -* **admin_password** - LDAP admin password. +- **domain_controller** + The domain controllers option is server name located on your network that serve Active Directory. +- **base_dn** + The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org. +- **login_attribute** + Login attribute like cn or uid +- **group_attribute** + Group attribute (e.g. memberOf in Active Directory). Required for [LDAP roles syncing][Settings#LDAP groups syncing] with internal roles. +- **port** + The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636). +- **use_ssl** + Use ssl for connection +- **use_tls** + Use tls for connection +- **timeout** + The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server. +- **admin_username** + LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com +- **admin_password** + LDAP admin password. ## Update settings @@ -92,32 +92,32 @@ Note that the PATCH HTTP method only requires partial JSON for an update. Such a **Headers:** -* **Authorization: api_token** *(string)* - Set token to access api. To get the token please look at - ```/var/cfengine/httpd/htdocs/ldap/config/settings.php``` +- **Authorization: api_token** _(string)_ + Set token to access api. To get the token please look at - `/var/cfengine/httpd/htdocs/ldap/config/settings.php` -* **Content-Type: application/json** *(string)* - Content-Type must be application/json for the API to parse JSON provided. +- **Content-Type: application/json** _(string)_ + Content-Type must be application/json for the API to parse JSON provided. **Parameters:** -* **domain_controller** *(string)* - The domain controllers option is server name located on your network that serve Active Directory. -* **base_dn** *(string)* - The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org. -* **login_attribute** *(string)* - Login attribute like cn or uid -* **port** *(integer)* - The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636). Optional parameter. -* **use_ssl** *(boolean)* - Use ssl for connection. Optional parameter. -* **use_tls** *(boolean)* - Use tls for connection. Optional parameter. -* **timeout** *(integer)* - The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server. Optional parameter. -* **admin_username** - LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com -* **admin_password** - LDAP admin password. +- **domain_controller** _(string)_ + The domain controllers option is server name located on your network that serve Active Directory. +- **base_dn** _(string)_ + The base distinguished name is the base distinguished name you'd like to perform operations on. An example base DN would be DC=corp,DC=acme,DC=org. +- **login_attribute** _(string)_ + Login attribute like cn or uid +- **port** _(integer)_ + The port option is used for authenticating and binding to your AD server. The default ports are already used for non SSL and SSL connections (389 and 636). Optional parameter. +- **use_ssl** _(boolean)_ + Use ssl for connection. Optional parameter. +- **use_tls** _(boolean)_ + Use tls for connection. Optional parameter. +- **timeout** _(integer)_ + The timeout option allows you to configure the amount of seconds to wait until your application receives a response from your LDAP server. Optional parameter. +- **admin_username** + LDAP admin distinguished name. Emp.: cn=admin,dc=jumpcloud,dc=com +- **admin_password** + LDAP admin password. **Example response:** diff --git a/content/api/enterprise-api-ref/personal-groups.markdown b/content/api/enterprise-api-ref/personal-groups.markdown index dbe64e8d1..28dba9a6d 100644 --- a/content/api/enterprise-api-ref/personal-groups.markdown +++ b/content/api/enterprise-api-ref/personal-groups.markdown @@ -2,6 +2,7 @@ layout: default title: Personal groups API --- + The personal groups API enables creating host groups based on host filters (the same ones used in inventory reports). ## Create group @@ -12,31 +13,31 @@ The personal groups API enables creating host groups based on host filters (the **Parameters:** -* **name** *(string)* +- **name** _(string)_ Group name. -* **description** *(string)* +- **description** _(string)_ Group description. -* **filter** *(json object)* Group filter object. Includes inventory filter and classes filters - * **filter** *(json object)* Optional parameter. - Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is - * **hostContextInclude** *(array)* Optional parameter. - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. - * **hostContextExclude** *(array)* Optional parameter. - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one - of the specified contexts set will be excluded from the results. - * **hostFilter** *(json object)* Optional parameter. - * **includes** *(json object)* Optional parameter. - Object that specifies hosts to be included. - * **includeAdditionally** *(boolean)* Default: `false` - Defines if hosts will be added to the results returned by inventory filters or class filters. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` - * **excludes** *(json object)* Optional parameter. - Object that specifies hosts to be excluded. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` +- **filter** _(json object)_ Group filter object. Includes inventory filter and classes filters + - **filter** _(json object)_ Optional parameter. + Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is + - **hostContextInclude** _(array)_ Optional parameter. + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. + - **hostContextExclude** _(array)_ Optional parameter. + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one + of the specified contexts set will be excluded from the results. + - **hostFilter** _(json object)_ Optional parameter. + - **includes** _(json object)_ Optional parameter. + Object that specifies hosts to be included. + - **includeAdditionally** _(boolean)_ Default: `false` + Defines if hosts will be added to the results returned by inventory filters or class filters. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` + - **excludes** _(json object)_ Optional parameter. + Object that specifies hosts to be excluded. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` ```json { @@ -74,7 +75,7 @@ The personal groups API enables creating host groups based on host filters (the For filtering you can use the operators below: | Operator | -|-----------------| +| --------------- | | < | | > | | = | @@ -158,33 +159,33 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Group id. -* **name** *(string)* +- **name** _(string)_ Group name. -* **description** *(string)* +- **description** _(string)_ Group description. -* **filter** *(json object)* Group filter object. Includes inventory filter and classes filters - * **filter** *(json object)* Optional parameter. - Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is - * **hostContextInclude** *(array)* Optional parameter. - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. - * **hostContextExclude** *(array)* Optional parameter. - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one - of the specified contexts set will be excluded from the results. - * **hostFilter** *(json object)* Optional parameter. - * **includes** *(json object)* Optional parameter. - Object that specifies hosts to be included. - * **includeAdditionally** *(boolean)* Default: `false` - Defines if hosts will be added to the results returned by inventory filters or class filters. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` - * **excludes** *(json object)* Optional parameter. - Object that specifies hosts to be excluded. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings - Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` +- **filter** _(json object)_ Group filter object. Includes inventory filter and classes filters + - **filter** _(json object)_ Optional parameter. + Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is + - **hostContextInclude** _(array)_ Optional parameter. + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. + - **hostContextExclude** _(array)_ Optional parameter. + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one + of the specified contexts set will be excluded from the results. + - **hostFilter** _(json object)_ Optional parameter. + - **includes** _(json object)_ Optional parameter. + Object that specifies hosts to be included. + - **includeAdditionally** _(boolean)_ Default: `false` + Defines if hosts will be added to the results returned by inventory filters or class filters. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` + - **excludes** _(json object)_ Optional parameter. + Object that specifies hosts to be excluded. + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings + Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` ```json { @@ -218,7 +219,7 @@ curl -k --user : \ For filtering you can use the operators below: | Operator | -|-----------------| +| --------------- | | < | | > | | = | @@ -273,7 +274,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Group id. **Example request:** @@ -311,7 +312,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Group id. **Example request:** @@ -382,7 +383,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Group id. **Example request:** diff --git a/content/api/enterprise-api-ref/query.markdown b/content/api/enterprise-api-ref/query.markdown index 2409a556a..511773833 100644 --- a/content/api/enterprise-api-ref/query.markdown +++ b/content/api/enterprise-api-ref/query.markdown @@ -19,21 +19,21 @@ API performance depend on the query result size, to achieve fastest results cons **Parameters:** -* **query** *(string)* - SQL query string. -* **sortColumn** *(string)* - Column name on which to sort results. Optional parameter. -* **sortDescending** *(boolean)* - Sorting order. Optional parameter. -* **skip** *(integer)* - Number of results to skip for the processed - query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* - Limit the number of results in the query. -* **hostContextInclude** *(array)* - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. -* **hostContextExclude** *(array)* - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. +- **query** _(string)_ + SQL query string. +- **sortColumn** _(string)_ + Column name on which to sort results. Optional parameter. +- **sortDescending** _(boolean)_ + Sorting order. Optional parameter. +- **skip** _(integer)_ + Number of results to skip for the processed + query. The Mission Portal uses this for pagination. Optional parameter. +- **limit** _(integer)_ + Limit the number of results in the query. +- **hostContextInclude** _(array)_ + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. +- **hostContextExclude** _(array)_ + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. **Example Request Body:** @@ -85,7 +85,7 @@ API performance depend on the query result size, to achieve fastest results cons } ``` -**Example usage:** `Synchronous Example: Listing hostname and IP for Ubuntu hosts` +**Example usage:** `Synchronous Example: Listing hostname and IP for Ubuntu hosts` ## Schedule SQL query as long running job @@ -103,14 +103,14 @@ API returns entire query result. Make sure that result size is sensible. **Parameters:** -* **query** *(string)* - SQL query string. -* **outputType** *(string)* - Supported types: 'csv' (default). Optional parameter. -* **hostContextInclude** *(array)* - Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. -* **hostContextExclude** *(array)* - Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. +- **query** _(string)_ + SQL query string. +- **outputType** _(string)_ + Supported types: 'csv' (default). Optional parameter. +- **hostContextInclude** _(array)_ + Includes only results that concern hosts which have all specified CFEngine contexts (class) set. Optional parameter. +- **hostContextExclude** _(array)_ + Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at lest one of the specified contexts set will be excluded from the results. Optional parameter. **Example Request Body:** diff --git a/content/api/enterprise-api-ref/reset-password.markdown b/content/api/enterprise-api-ref/reset-password.markdown index f17e9746a..71fa9636a 100644 --- a/content/api/enterprise-api-ref/reset-password.markdown +++ b/content/api/enterprise-api-ref/reset-password.markdown @@ -31,10 +31,10 @@ Reset password email successfully sent. **Responses:** -| HTTP response code | Description | -|--------------------------|---------------------------------------------------------------| -| 200 OK | Check your email for the link to reset your password. | -| 422 Unprocessable Entity | We are unable to reset the password at this time. | +| HTTP response code | Description | +| ------------------------ | ----------------------------------------------------- | +| 200 OK | Check your email for the link to reset your password. | +| 422 Unprocessable Entity | We are unable to reset the password at this time. | ## Reset password by token @@ -64,7 +64,7 @@ Reset password email successfully sent. **Responses:** | HTTP response code | Description | -|--------------------------|-----------------------------------------------------------------| +| ------------------------ | --------------------------------------------------------------- | | 200 OK | Password successfully changed. | | 422 Unprocessable Entity | Password validation error or the request cannot be processed. | | 429 Too Many Requests | We have detected multiple unsuccessful reset password attempts. | @@ -95,6 +95,6 @@ Reset password token successfully invalidated. **Responses:** | HTTP response code | Description | -|--------------------------|------------------------------------------------| +| ------------------------ | ---------------------------------------------- | | 202 Accepted | Reset password token successfully invalidated. | | 422 Unprocessable Entity | Unable to process request. | diff --git a/content/api/enterprise-api-ref/shared-groups.markdown b/content/api/enterprise-api-ref/shared-groups.markdown index 943703350..701bcd37b 100644 --- a/content/api/enterprise-api-ref/shared-groups.markdown +++ b/content/api/enterprise-api-ref/shared-groups.markdown @@ -2,6 +2,7 @@ layout: default title: Shared groups API --- + The shared groups API enables creating host groups based on host filters (the same ones used in inventory) and assigning CMDB data to them. ## Create group @@ -12,33 +13,33 @@ The shared groups API enables creating host groups based on host filters (the sa **Parameters:** -* **name** *(string)* +- **name** _(string)_ Group name. -* **description** *(string)* +- **description** _(string)_ Group description. -* **priority** *(number)* +- **priority** _(number)_ Group priority. Groups with a higher priority will take precedence in case of conflicts when merging CMDB data. (A lower number indicates higher priority, so 1 means 1st priority, 2 means 2nd most important, and so on). -* **filter** *(json object)* Group filter object. Includes inventory filter and classes filters - * **filter** *(json object)* Optional parameter. +- **filter** _(json object)_ Group filter object. Includes inventory filter and classes filters + - **filter** _(json object)_ Optional parameter. Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is - * **hostContextInclude** *(array)* Optional parameter. + - **hostContextInclude** _(array)_ Optional parameter. Includes only results that concern hosts which have all specified CFEngine contexts (class) set. - * **hostContextExclude** *(array)* Optional parameter. + - **hostContextExclude** _(array)_ Optional parameter. Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. - * **hostFilter** *(json object)* Optional parameter. - * **includes** *(json object)* Optional parameter. + - **hostFilter** _(json object)_ Optional parameter. + - **includes** _(json object)_ Optional parameter. Object that specifies hosts to be included. - * **includeAdditionally** *(boolean)* Default: `false` + - **includeAdditionally** _(boolean)_ Default: `false` Defines if hosts will be added to the results returned by inventory filters or class filters. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` - * **excludes** *(json object)* Optional parameter. + - **excludes** _(json object)_ Optional parameter. Object that specifies hosts to be excluded. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` ```json @@ -77,7 +78,7 @@ The shared groups API enables creating host groups based on host filters (the sa For filtering you can use the operators below: | Operator | -|-----------------| +| --------------- | | < | | > | | = | @@ -130,36 +131,36 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. -* **name** *(string)* +- **name** _(string)_ Group name. -* **priority** *(number)* +- **priority** _(number)_ Group priority. Groups with a higher priority will take precedence in case of conflicts when merging CMDB data. (A lower number indicates higher priority, so 1 means 1st priority, 2 means 2nd most important, and so on). -* **description** *(string)* +- **description** _(string)_ Group description. -* **filter** *(json object)* Group filter object. Includes inventory filter and classes filters - * **filter** *(json object)* Optional parameter. +- **filter** _(json object)_ Group filter object. Includes inventory filter and classes filters + - **filter** _(json object)_ Optional parameter. Inventory filter data. You can use array values for multiple filter, the logic will be AND. Format is - * **hostContextInclude** *(array)* Optional parameter. + - **hostContextInclude** _(array)_ Optional parameter. Includes only results that concern hosts which have all specified CFEngine contexts (class) set. - * **hostContextExclude** *(array)* Optional parameter. + - **hostContextExclude** _(array)_ Optional parameter. Excludes results that concern hosts which have specified CFEngine context (class) set. Hosts that have at least one of the specified contexts set will be excluded from the results. - * **hostFilter** *(json object)* Optional parameter. - * **includes** *(json object)* Optional parameter. + - **hostFilter** _(json object)_ Optional parameter. + - **includes** _(json object)_ Optional parameter. Object that specifies hosts to be included. - * **includeAdditionally** *(boolean)* Default: `false` + - **includeAdditionally** _(boolean)_ Default: `false` Defines if hosts will be added to the results returned by inventory filters or class filters. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` - * **excludes** *(json object)* Optional parameter. + - **excludes** _(json object)_ Optional parameter. Object that specifies hosts to be excluded. - * **entries** *(json object)* Filter entries object. Where the key is an entry type and the value is an array of strings + - **entries** _(json object)_ Filter entries object. Where the key is an entry type and the value is an array of strings Allowed entry types: `hostkey`, `hostname`, `ip`, `mac`, `ip_mask` ```json @@ -198,7 +199,7 @@ curl -k --user : \ For filtering you can use the operators below: | Operator | -|-----------------| +| --------------- | | < | | > | | = | @@ -253,7 +254,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. **Example request:** @@ -292,7 +293,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. **Example request:** @@ -365,7 +366,7 @@ curl -k --user : \ **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. **Example request:** @@ -400,21 +401,21 @@ You can see a list of stored group-specific configurations **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. -* **fromEpoch** *(integer)* +- **fromEpoch** _(integer)_ Returns configurations with epoch value greater than set in the filter. Epoch is the sequence number of the latest CMDB change. In every API list request, `cmdb_epoch` will be present in the meta section, which contains the maximum epoch value among selected items. Optional parameter. -* **fromTime** *(timestamp)* +- **fromTime** _(timestamp)_ Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` or `YYYY-mm-dd`. Optional parameter. -* **toTime** *(timestamp)* +- **toTime** _(timestamp)_ Include changes performed within interval. Format: `YYYY-mm-dd HH:MM:SS` or `YYYY-mm-dd`. Optional parameter. -* **skip** *(integer)* +- **skip** _(integer)_ Number of results to skip for the processed query. The Mission Portal uses this for pagination. Optional parameter. -* **limit** *(integer)* +- **limit** _(integer)_ Limit the number of results in the query. Optional parameter. **Example request (curl):** @@ -467,13 +468,13 @@ HTTP 200 Ok **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ Unique group identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Example request (curl):** @@ -510,7 +511,7 @@ HTTP 200 Ok **Parameters:** -* **id** *(string)* +- **id** _(string)_ Unique group identifier. **Example request (curl):** @@ -555,24 +556,24 @@ HTTP 200 Ok **Parameters:** -* **id** *(string)* +- **id** _(string)_ Unique group identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Request body parameters:** -* **value** *(string|array)* +- **value** _(string|array)_ Variable value, can be array or text. Classes do not support values. -* **comment** *(string)* +- **comment** _(string)_ Variables or classes description. Optional parameter. -* **tags** *(array)* +- **tags** _(array)_ Variables or classes tags. Optional parameter. **Example request (curl):** @@ -603,27 +604,27 @@ HTTP 200 Ok **Parameters:** -* **id** *(string)* +- **id** _(string)_ Unique group identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Request body parameters:** -* **value** *(string|array)* +- **value** _(string|array)_ Variable value, can be array or text. Classes do not support values. -* **comment** *(string)* +- **comment** _(string)_ Variables or classes description. Optional parameter. -* **tags** *(array)* +- **tags** _(array)_ Variables or classes tags. Optional parameter. -* **name** *(string)* +- **name** _(string)_ New name, in case of renaming. Optional parameter. **Example request (curl):** @@ -654,7 +655,7 @@ HTTP 200 Ok **Parameters:** -* **id** *(string)* +- **id** _(string)_ Unique group identifier. **Example request (curl):** @@ -679,13 +680,13 @@ HTTP 204 No Content **Parameters:** -* **id** *(string)* +- **id** _(string)_ Unique group identifier. -* **type** *(string)* +- **type** _(string)_ Configuration type. Allowed value: `variables`, `classes` -* **name** *(string)* +- **name** _(string)_ Configuration name. Classes or variables name. **Example request (curl):** diff --git a/content/api/enterprise-api-ref/sql-schema/cfdb.markdown b/content/api/enterprise-api-ref/sql-schema/cfdb.markdown index 4e02ab57d..7302a0f7e 100644 --- a/content/api/enterprise-api-ref/sql-schema/cfdb.markdown +++ b/content/api/enterprise-api-ref/sql-schema/cfdb.markdown @@ -16,17 +16,17 @@ Agent status contains information about last cf-agent execution. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **AgentExecutionInterval** *(integer)* - Estimated interval in which cf-agent is being executed, as cf-agent execution interval is expressed in CFEngine context expressions (Min00_05 etc.) it can be not regular, this interval is discovered by analyzing last few cf-agent execution timestamps. Expressed in seconds. +- **AgentExecutionInterval** _(integer)_ + Estimated interval in which cf-agent is being executed, as cf-agent execution interval is expressed in CFEngine context expressions (Min00_05 etc.) it can be not regular, this interval is discovered by analyzing last few cf-agent execution timestamps. Expressed in seconds. -* **LastAgentLocalExecutionTimeStamp** *(timestamp)* - Timestamp of last cf-agent execution on the host. +- **LastAgentLocalExecutionTimeStamp** _(timestamp)_ + Timestamp of last cf-agent execution on the host. -* **LastAgentExecutionStatus** *(`OK`/`FAIL`)* - cf-agent execution status. In case cf-agent will not execute within 3x `AgentExecutionInterval` from last execution, status will be set to `FAIL`. Failure may indicate cf-execd issues, or cf-agent crashes. +- **LastAgentExecutionStatus** _(`OK`/`FAIL`)_ + cf-agent execution status. In case cf-agent will not execute within 3x `AgentExecutionInterval` from last execution, status will be set to `FAIL`. Failure may indicate cf-execd issues, or cf-agent crashes. **Example query:** @@ -64,23 +64,23 @@ Data from internal cf-agent monitoring as also [measurements promises][measureme **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **EventName** *(text)* - Name of measured event. +- **EventName** _(text)_ + Name of measured event. -* **StandardDeviation** *(numeric)* - Dispersion of a set of data from its mean. +- **StandardDeviation** _(numeric)_ + Dispersion of a set of data from its mean. -* **AverageValue** *(numeric)* - Average value. +- **AverageValue** _(numeric)_ + Average value. -* **LastValue** *(numeric)* - Last measured value. +- **LastValue** _(numeric)_ + Last measured value. -* **CheckTimeStamp** *(timestamp)* - Measurement time. +- **CheckTimeStamp** _(timestamp)_ + Measurement time. **Example query:** @@ -126,18 +126,18 @@ CFEngine contexts present on hosts at their last reported cf-agent execution. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ContextName** *(text)* - CFEngine [context][Classes and decisions] set by cf-agent. +- **ContextName** _(text)_ + CFEngine [context][Classes and decisions] set by cf-agent. -* **MetaTags** *(text[])* - List of [meta tags][Tags for variables, classes, and bundles] set for the context. +- **MetaTags** _(text[])_ + List of [meta tags][Tags for variables, classes, and bundles] set for the context. -* **ChangeTimeStamp** *(timestamp)* - Timestamp since when context is set in its current form. - **Note:** If any of the context attributes change, the timestamp will be updated. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp since when context is set in its current form. + **Note:** If any of the context attributes change, the timestamp will be updated. **Example query:** @@ -175,25 +175,25 @@ CFEngine contexts set on hosts by CFEngine over period of time. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - Timestamp since when context is set in its current form. - **Note:** The statement if true till present time or newer entry claims otherwise. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp since when context is set in its current form. + **Note:** The statement if true till present time or newer entry claims otherwise. -* **ChangeOperation** *(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `ADD` - stands for introducing a new entry which did not exist before. In this case, new CFEngine context have been introduced. - * `CHANGE` - stands for changing value or attribute such as `MetaTags` have changed. - * `REMOVE` - Context have not been set. - * `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information about this context is being filtered and will not report any future information about it. +- **ChangeOperation** _(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `ADD` - stands for introducing a new entry which did not exist before. In this case, new CFEngine context have been introduced. + - `CHANGE` - stands for changing value or attribute such as `MetaTags` have changed. + - `REMOVE` - Context have not been set. + - `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information about this context is being filtered and will not report any future information about it. -* **ContextName** *(text)* - CFEngine [context][Classes and decisions] set by cf-agent. +- **ContextName** _(text)_ + CFEngine [context][Classes and decisions] set by cf-agent. -* **MetaTags** *(text[])* - List of [meta tags][Tags for variables, classes, and bundles] set for the context. +- **MetaTags** _(text[])_ + List of [meta tags][Tags for variables, classes, and bundles] set for the context. **Example query:** @@ -235,26 +235,26 @@ Log of changes detected to files that are set to be [monitored][files#changes] b **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **PromiseHandle** *(text)* - A Uniqueue id-tag string for referring promise. +- **PromiseHandle** _(text)_ + A Uniqueue id-tag string for referring promise. -* **FileName** *(text)* - Name of the file that have changed. +- **FileName** _(text)_ + Name of the file that have changed. -* **ChangeTimeStamp** *(timestamp)* - Timestamp when CFEngine have detected the change to the file. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when CFEngine have detected the change to the file. -* **ChangeType** *(text)* - Type of change detected on the monitored file. - * DIFF - change in content (with file diff) - * S - change in file stats - * C - change in content (based on file hash) +- **ChangeType** _(text)_ + Type of change detected on the monitored file. + - DIFF - change in content (with file diff) + - S - change in file stats + - C - change in content (based on file hash) -* **ChangeDetails** *(text[])* - Information about changes detected to the file. Such as file stats information, file diff etc. +- **ChangeDetails** _(text[])_ + Information about changes detected to the file. Such as file stats information, file diff etc. **Example query:** @@ -300,26 +300,26 @@ Hosts table contains basic information about hosts managed by CFEngine. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **HostName** *(text)* - Host name locally detected on the host, configurable as `hostIdentifier` - option in [Settings API][Status and settings REST API#Get settings] and - Mission Portal settings UI. +- **HostName** _(text)_ + Host name locally detected on the host, configurable as `hostIdentifier` + option in [Settings API][Status and settings REST API#Get settings] and + Mission Portal settings UI. -* **IPAddress** *(text)* - IP address of the host derived from the lastseen database (this is expected - to be the IP address from which connections come from, beware NAT will cause - multiple hosts to appear to have the same IP address). +- **IPAddress** _(text)_ + IP address of the host derived from the lastseen database (this is expected + to be the IP address from which connections come from, beware NAT will cause + multiple hosts to appear to have the same IP address). -* **LastReportTimeStamp** *(timestamp)* - Timestamp of the most recent successful report collection. +- **LastReportTimeStamp** _(timestamp)_ + Timestamp of the most recent successful report collection. -* **FirstReportTimeStamp** *(timestamp)* - Timestamp when the host reported to the hub for the first time, which - indicate when the host was bootstrapped to the hub. +- **FirstReportTimeStamp** _(timestamp)_ + Timestamp when the host reported to the hub for the first time, which + indicate when the host was bootstrapped to the hub. **Example query:** @@ -361,19 +361,19 @@ Hosts_not_reported table contains information about not reported hosts. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **iscallcollected** *(boolean)* - Is host call collected +- **iscallcollected** _(boolean)_ + Is host call collected -* **LastReportTimeStamp** *(timestamp)* - Timestamp of the most recent successful report collection. +- **LastReportTimeStamp** _(timestamp)_ + Timestamp of the most recent successful report collection. -* **FirstReportTimeStamp** *(timestamp)* - Timestamp when the host reported to the hub for the first time, which - indicate when the host was bootstrapped to the hub. +- **FirstReportTimeStamp** _(timestamp)_ + Timestamp when the host reported to the hub for the first time, which + indicate when the host was bootstrapped to the hub. **Example query:** @@ -411,17 +411,17 @@ Networking errors encountered by cf-hub during its operation. **Columns:** -* **HostKey** *(text)* - Unique identifier of the host that cf-hub was connecting to. +- **HostKey** _(text)_ + Unique identifier of the host that cf-hub was connecting to. -* **CheckTimeStamp** *(timestamp)* - Timestamp when the error occurred. +- **CheckTimeStamp** _(timestamp)_ + Timestamp when the error occurred. -* **Message** *(text)* - Error type / message. +- **Message** _(text)_ + Error type / message. -* **QueryType** *(text)* - Type of query that was intended to be sent by hub during failed connection attempt. +- **QueryType** _(text)_ + Type of query that was intended to be sent by hub during failed connection attempt. **Example query:** @@ -459,22 +459,22 @@ Inventory data **Columns:** -* **HostKey** *(text)* - Unique identifier of the host. +- **HostKey** _(text)_ + Unique identifier of the host. -* **keyname** *(text)* - Name of the key. +- **keyname** _(text)_ + Name of the key. -* **type** *(text)* - Type of the variable. [List][Variables] of supported variable types. +- **type** _(text)_ + Type of the variable. [List][Variables] of supported variable types. -* **metatags** *(text[])* - List of [meta tags][Tags for variables, classes, and bundles] set for the variable. +- **metatags** _(text[])_ + List of [meta tags][Tags for variables, classes, and bundles] set for the variable. -* **value** *(text)* - Variable value serialized to string. - * List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. - * `Data` type is serialized as JSON string. +- **value** _(text)_ + Variable value serialized to string. + _ List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. + _ `Data` type is serialized as JSON string. **Example query:** @@ -510,11 +510,11 @@ Inventory data grouped by host **Columns:** -* **HostKey** *(text)* - Unique identifier of the host. +- **HostKey** _(text)_ + Unique identifier of the host. -* **values** *(jsonb)* - Inventory values presented in JSON format +- **values** _(jsonb)_ + Inventory values presented in JSON format **Example query:** @@ -543,25 +543,25 @@ their last reported `cf-agent` execution. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **LastSeenDirection** *(`INCOMING`/`OUTGOING`)* - Direction within which the connection was established. - * `INCOMING` - host received incoming connection. - * `OUTGOING` - host opened connection to remote host. +- **LastSeenDirection** _(`INCOMING`/`OUTGOING`)_ + Direction within which the connection was established. + - `INCOMING` - host received incoming connection. + - `OUTGOING` - host opened connection to remote host. -* **RemoteHostKey** *(text)* - `HostKey` of the remote host. +- **RemoteHostKey** _(text)_ + `HostKey` of the remote host. -* **RemoteHostIP** *(text)* - IP address of the remote host. +- **RemoteHostIP** _(text)_ + IP address of the remote host. -* **LastSeenTimeStamp** *(timestamp)* - Time when the connection was established. +- **LastSeenTimeStamp** _(timestamp)_ + Time when the connection was established. -* **LastSeenInterval** *(real)* - Average time period (seconds) between connections for the given `LastSeenDirection` with the host. +- **LastSeenInterval** _(real)_ + Average time period (seconds) between connections for the given `LastSeenDirection` with the host. **Example query:** @@ -607,25 +607,25 @@ History of LastSeenHosts table **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **LastSeenDirection** *(`INCOMING`/`OUTGOING`)* - Direction within which the connection was established. - * `INCOMING` - host received incoming connection. - * `OUTGOING` - host opened connection to remote host. +- **LastSeenDirection** _(`INCOMING`/`OUTGOING`)_ + Direction within which the connection was established. + - `INCOMING` - host received incoming connection. + - `OUTGOING` - host opened connection to remote host. -* **RemoteHostKey** *(text)* - `HostKey` of the remote host. +- **RemoteHostKey** _(text)_ + `HostKey` of the remote host. -* **RemoteHostIP** *(text)* - IP address of the remote host. +- **RemoteHostIP** _(text)_ + IP address of the remote host. -* **LastSeenTimeStamp** *(timestamp)* - Time when the connection was established. +- **LastSeenTimeStamp** _(timestamp)_ + Time when the connection was established. -* **LastSeenInterval** *(real)* - Average time period (seconds) between connections for the given `LastSeenDirection` with the host. +- **LastSeenInterval** _(real)_ + Average time period (seconds) between connections for the given `LastSeenDirection` with the host. **Example query:** @@ -671,15 +671,15 @@ Stores 1 record for each observable per host. **Columns:** -* **host** *(text)* - Unique host identifier. Referred to in other tables as `HostKey` to connect - data concerning same hosts. +- **host** _(text)_ + Unique host identifier. Referred to in other tables as `HostKey` to connect + data concerning same hosts. -* **id** *(text)* - Name of monitored metric. The handle of the measurement promise. +- **id** _(text)_ + Name of monitored metric. The handle of the measurement promise. -* **ar1** *(real)* - Average across 66 observations. +- **ar1** _(real)_ + Average across 66 observations. ## Table: MonitoringMgMeta @@ -687,35 +687,35 @@ Stores 1 record for each observable per host. **Columns:** -* **id** *(integer)* - Unique identifier for host observable. +- **id** _(integer)_ + Unique identifier for host observable. -* **hostkey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **hostkey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **observable** *(text)* - Name of monitored metric. The handle of the measurement promise. +- **observable** _(text)_ + Name of monitored metric. The handle of the measurement promise. -* **global** *(boolean)* +- **global** _(boolean)_ -* **expected_min** *(real)* - Minimum expected value. +- **expected_min** _(real)_ + Minimum expected value. -* **expected_max** *(real)* - Maximum expected value. +- **expected_max** _(real)_ + Maximum expected value. -* **unit** *(text)* - Unit of measurement. +- **unit** _(text)_ + Unit of measurement. -* **description** *(text)* - Description of unit of measurement. +- **description** _(text)_ + Description of unit of measurement. -* **updatedtimestamp** *(timestamp with time zone)* - Time when measurement sampled. +- **updatedtimestamp** _(timestamp with time zone)_ + Time when measurement sampled. -* **lastupdatedsample** *(integer)* - Value of most recently collected measurement. +- **lastupdatedsample** _(integer)_ + Value of most recently collected measurement. ## Table: MonitoringYrMeta @@ -723,32 +723,32 @@ Stores 1 record for each observable per host. **Columns:** -* **id** *(integer)* - Unique identifier for host observable. +- **id** _(integer)_ + Unique identifier for host observable. -* **hostkey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **hostkey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **observable** *(text)* - Name of monitored metric. The handle of the measurement promise. +- **observable** _(text)_ + Name of monitored metric. The handle of the measurement promise. -* **global** *(boolean)* +- **global** _(boolean)_ -* **expected_min** *(real)* - Minimum expected value. +- **expected_min** _(real)_ + Minimum expected value. -* **expected_max** *(real)* - Maximum expected value. +- **expected_max** _(real)_ + Maximum expected value. -* **unit** *(text)* - Unit of measurement. +- **unit** _(text)_ + Unit of measurement. -* **description** *(text)* - Description of unit of measurement. +- **description** _(text)_ + Description of unit of measurement. -* **lastupdatedsample** *(integer)* - Value of most recently collected measurement. +- **lastupdatedsample** _(integer)_ + Value of most recently collected measurement. ## Table: PromiseExecutions @@ -756,51 +756,51 @@ Promises executed on hosts during their last reported cf-agent run. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **PolicyFile** *(text)* - Path to the file where the promise is located in. +- **PolicyFile** _(text)_ + Path to the file where the promise is located in. -* **ReleaseId** *(text)* - Unique identifier of masterfiles version that is executed on the host. +- **ReleaseId** _(text)_ + Unique identifier of masterfiles version that is executed on the host. -* **PromiseHash** *(text)* - Unique identifier of a promise. It is a hash of all promise attributes and their values. +- **PromiseHash** _(text)_ + Unique identifier of a promise. It is a hash of all promise attributes and their values. -* **NameSpace** *(text)* - [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. +- **NameSpace** _(text)_ + [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. -* **BundleName** *(text)* - [Bundle][Bundles] name where the promise is executed. +- **BundleName** _(text)_ + [Bundle][Bundles] name where the promise is executed. -* **PromiseType** *(text)* - [Type][Promise types] of the promise. +- **PromiseType** _(text)_ + [Type][Promise types] of the promise. -* **Promiser** *(text)* - Object affected by a promise. +- **Promiser** _(text)_ + Object affected by a promise. -* **StackPath** *(text)* - Call stack of the promise. +- **StackPath** _(text)_ + Call stack of the promise. -* **PromiseHandle** *(text)* - A unique id-tag string for referring promise. +- **PromiseHandle** _(text)_ + A unique id-tag string for referring promise. -* **PromiseOutcome** *(`KEPT`/`NOTKEPT`/`REPAIRED`)* - Promise execution result. - * `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. - * `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. - * `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. +- **PromiseOutcome** _(`KEPT`/`NOTKEPT`/`REPAIRED`)_ + Promise execution result. + - `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. + - `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. + - `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. -* **LogMessages** *(text[])* - List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. +- **LogMessages** _(text[])_ + List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. -* **Promisees** *(text[])* - List of [promisees][Promises] defined for the promise. +- **Promisees** _(text[])_ + List of [promisees][Promises] defined for the promise. -* **ChangeTimeStamp** *(timestamp)* - Timestamp since when the promise is continuously executed by cf-agent in its current configuration and provides the same output. - **Note:** If any of the promise dynamic attributes change, like promise outcome, log messages or the new policy version will be rolled out. This timestamp will be changed. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp since when the promise is continuously executed by cf-agent in its current configuration and provides the same output. + **Note:** If any of the promise dynamic attributes change, like promise outcome, log messages or the new policy version will be rolled out. This timestamp will be changed. **Example query:** @@ -880,58 +880,58 @@ Promise status / outcome changes over period of time. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - Timestamp when the promise state or outcome changed. - **Note:** The statement if true till present time or newer entry claims otherwise. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when the promise state or outcome changed. + **Note:** The statement if true till present time or newer entry claims otherwise. -* **ChangeOperation** *(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `ADD` - stands for introducing a new entry which did not exist at last execution. In this case, new promise executed, or the promise was not executed at previous cf-agent run. - * `CHANGE` - stands for changing value or attribute such as `PromiseOutcome`, `LogMessages` or `ReleaseId` in case of new policy rollout. - * `REMOVE` - Promise was not executed last time, but it was executed previously. This is a common report for promises that have been removed from policy at some point, or they are executed only periodically (like once a hour, day etc.). - * `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information is being filtered and will not report any future information about it. +- **ChangeOperation** _(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `ADD` - stands for introducing a new entry which did not exist at last execution. In this case, new promise executed, or the promise was not executed at previous cf-agent run. + - `CHANGE` - stands for changing value or attribute such as `PromiseOutcome`, `LogMessages` or `ReleaseId` in case of new policy rollout. + - `REMOVE` - Promise was not executed last time, but it was executed previously. This is a common report for promises that have been removed from policy at some point, or they are executed only periodically (like once a hour, day etc.). + - `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information is being filtered and will not report any future information about it. -* **PolicyFile** *(text)* - Path to the file where the promise is located in. +- **PolicyFile** _(text)_ + Path to the file where the promise is located in. -* **ReleaseId** *(text)* - Unique identifier of masterfiles version that is executed in the host. +- **ReleaseId** _(text)_ + Unique identifier of masterfiles version that is executed in the host. -* **PromiseHash** *(text)* - Unique identifier of a promise. It is a hash of all promise attributes and their values. +- **PromiseHash** _(text)_ + Unique identifier of a promise. It is a hash of all promise attributes and their values. -* **NameSpace** *(text)* - [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. +- **NameSpace** _(text)_ + [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. -* **BundleName** *(text)* - [Bundle][Bundles] name where the promise is executed. +- **BundleName** _(text)_ + [Bundle][Bundles] name where the promise is executed. -* **PromiseType** *(text)* - [Type][Promise types] of the promise. +- **PromiseType** _(text)_ + [Type][Promise types] of the promise. -* **Promiser** *(text)* - Object affected by a promise. +- **Promiser** _(text)_ + Object affected by a promise. -* **StackPath** *(text)* - Call stack of the promise. +- **StackPath** _(text)_ + Call stack of the promise. -* **PromiseHandle** *(text)* - A unique id-tag string for referring promise. +- **PromiseHandle** _(text)_ + A unique id-tag string for referring promise. -* **PromiseOutcome** *(`KEPT`/`NOTKEPT`/`REPAIRED`)* - Promise execution result. - * `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. - * `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. - * `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. +- **PromiseOutcome** _(`KEPT`/`NOTKEPT`/`REPAIRED`)_ + Promise execution result. + - `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. + - `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. + - `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. -* **LogMessages** *(text[])* - List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. +- **LogMessages** _(text[])_ + List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. -* **Promisees** *(text[])* - List of [promisees][Promises] defined for the promise. +- **Promisees** _(text[])_ + List of [promisees][Promises] defined for the promise. **Example query:** @@ -1013,58 +1013,58 @@ History of promises executed on hosts. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - The GMT time on the host when this state was first perceived. +- **ChangeTimeStamp** _(timestamp)_ + The GMT time on the host when this state was first perceived. - **Note causes of change:** - - A change in the promise signature/hash for example, altering the promise - handle, promisees, or moving the promise to a different bundle - - A change in the policy releaseId (cf_promises_release_id) - - A change in promise outcome + **Note causes of change:** + - A change in the promise signature/hash for example, altering the promise + handle, promisees, or moving the promise to a different bundle + - A change in the policy releaseId (cf_promises_release_id) + - A change in promise outcome -* **PolicyFile** *(text)* - Path to the file where the promise is located in. +- **PolicyFile** _(text)_ + Path to the file where the promise is located in. -* **ReleaseId** *(text)* - Unique identifier of masterfiles version that is executed on the host. +- **ReleaseId** _(text)_ + Unique identifier of masterfiles version that is executed on the host. -* **PromiseHash** *(text)* - Unique identifier of a promise. It is a hash of all promise attributes and their values. +- **PromiseHash** _(text)_ + Unique identifier of a promise. It is a hash of all promise attributes and their values. -* **NameSpace** *(text)* - [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. +- **NameSpace** _(text)_ + [Namespace][Namespaces] within which the promise is executed. If no namespace is set then it is set as: `default`. -* **BundleName** *(text)* - [Bundle][Bundles] name where the promise is executed. +- **BundleName** _(text)_ + [Bundle][Bundles] name where the promise is executed. -* **PromiseType** *(text)* - [Type][Promise types] of the promise. +- **PromiseType** _(text)_ + [Type][Promise types] of the promise. -* **Promiser** *(text)* - Object affected by a promise. +- **Promiser** _(text)_ + Object affected by a promise. -* **StackPath** *(text)* - Call stack of the promise. +- **StackPath** _(text)_ + Call stack of the promise. -* **PromiseHandle** *(text)* - A unique id-tag string for referring promise. +- **PromiseHandle** _(text)_ + A unique id-tag string for referring promise. -* **PromiseOutcome** *(`KEPT`/`NOTKEPT`/`REPAIRED`)* - Promise execution result. - * `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. - * `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. - * `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. +- **PromiseOutcome** _(`KEPT`/`NOTKEPT`/`REPAIRED`)_ + Promise execution result. + - `KEPT` - System has been found in the state as desired by the promise. CFEngine did not have to do any action to correct the state. + - `REPAIRED` - State of the system differed from the desired state. CFEngine took successful action to correct it according to promise specification. + - `NOTKEPT` - CFEngine has failed to converge the system according to the promise specification. -* **LogMessages** *(text[])* - List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. +- **LogMessages** _(text[])_ + List of 5 last messages generated during promise execution. If the promise is `KEPT` the messages are not reported. Log messages can be used for tracking specific changes made by CFEngine while repairing or failing promise execution. -* **Promisees** *(text[])* - List of [promisees][Promises] defined for the promise. +- **Promisees** _(text[])_ + List of [promisees][Promises] defined for the promise. **Example query:** @@ -1116,20 +1116,20 @@ More information about CFEngine and package management can be found [here][packa **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **SoftwareName** *(text)* - Name of installed software package. +- **SoftwareName** _(text)_ + Name of installed software package. -* **SoftwareVersion** *(text)* - Software package version. +- **SoftwareVersion** _(text)_ + Software package version. -* **SoftwareArchitecture** *(text)* - Architecture. +- **SoftwareArchitecture** _(text)_ + Architecture. -* **ChangeTimeStamp** *(timestamp)* - Timestamp when the package was discovered / installed on the host. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when the package was discovered / installed on the host. **Example query:** @@ -1172,23 +1172,23 @@ The most up to date patch will be listed. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **PatchName** *(text)* - Name of the software. +- **PatchName** _(text)_ + Name of the software. -* **PatchVersion** *(text)* - Patch version. +- **PatchVersion** _(text)_ + Patch version. -* **PatchArchitecture** *(text)* - Architecture of the patch. +- **PatchArchitecture** _(text)_ + Architecture of the patch. -* **PatchReportType** *(`INSTALLED`/`AVAILABLE`)* - Patch status (`INSTALLED` status is specific only to SUSE Linux). +- **PatchReportType** _(`INSTALLED`/`AVAILABLE`)_ + Patch status (`INSTALLED` status is specific only to SUSE Linux). -* **ChangeTimeStamp** *(timestamp)* - Timestamp when the new patch / version was discovered as available on the host. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when the new patch / version was discovered as available on the host. **Example query:** @@ -1229,31 +1229,32 @@ changetimestamp | 2015-03-12 10:20:18+00 ``` ## Table: SoftwareLog + Software packages installed / deleted over period of time. More information about CFEngine and package management can be found [here][packages]. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - Timestamp when the package state was discovered on the host. - **Note:** The statement if true till present time or newer entry claims otherwise. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when the package state was discovered on the host. + **Note:** The statement if true till present time or newer entry claims otherwise. -* **ChangeOperation** *(`ADD`,`REMOVE`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `ADD` - New package have been detected / installed. Package upgrate is considered as installing a new package with a different version. - * `REMOVE` - Package have been detected to be removed / uninstalled. During upgrate older version of the package is removed and reported as so. +- **ChangeOperation** _(`ADD`,`REMOVE`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `ADD` - New package have been detected / installed. Package upgrate is considered as installing a new package with a different version. + - `REMOVE` - Package have been detected to be removed / uninstalled. During upgrate older version of the package is removed and reported as so. -* **SoftwareName** *(text)* - Name of installed software package. +- **SoftwareName** _(text)_ + Name of installed software package. -* **SoftwareVersion** *(text)* - Software package version. +- **SoftwareVersion** _(text)_ + Software package version. -* **SoftwareArchitecture** *(text)* - Architecture. +- **SoftwareArchitecture** _(text)_ + Architecture. **Example query:** @@ -1301,30 +1302,30 @@ Patches available for installed packages on the hosts (as reported by local pack **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - Timestamp when the patch state was discovered on the host. - **Note:** The statement if true till present time or newer entry claims otherwise. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp when the patch state was discovered on the host. + **Note:** The statement if true till present time or newer entry claims otherwise. -* **ChangeOperation** *(`ADD`,`REMOVE`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `ADD` - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available. - * `REMOVE` - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. +- **ChangeOperation** _(`ADD`,`REMOVE`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `ADD` - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available. + - `REMOVE` - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. **Note:** CFEngine reports only the most up to date version available. -* **PatchName** *(text)* - Name of the software. +- **PatchName** _(text)_ + Name of the software. -* **PatchVersion** *(text)* - Patch version. +- **PatchVersion** _(text)_ + Patch version. -* **PatchArchitecture** *(text)* - Architecture of the patch. +- **PatchArchitecture** _(text)_ + Architecture of the patch. -* **PatchReportType** *(`INSTALLED`/`AVAILABLE`)* - Patch status (`INSTALLED` status is specific only to SUSE Linux). +- **PatchReportType** _(`INSTALLED`/`AVAILABLE`)_ + Patch status (`INSTALLED` status is specific only to SUSE Linux). **Example query:** @@ -1374,29 +1375,29 @@ Statuses of report collection. cf-hub records all collection attempts and whethe **Columns:** -* **host** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **host** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ts** *(timestamp)* - Timestamp of last data provided by client during report collection. This is used by delta queries to request a start time. +- **ts** _(timestamp)_ + Timestamp of last data provided by client during report collection. This is used by delta queries to request a start time. -* **status** *(`FAILEDC`,`CONSUMED`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `FAILEDC` - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available. - * `CONSUMED` - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. +- **status** _(`FAILEDC`,`CONSUMED`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `FAILEDC` - New patch have been detected. This is a common in case of release of new patch version or new package was installed that have an upgrate available. + - `CONSUMED` - Patch is not longer available. Patch may be replaced with newer version, or installed package have been upgrated. **Note:** CFEngine reports only the most up to date version available. -* **lstatus** *(text)* - Deprecated +- **lstatus** _(text)_ + Deprecated -* **type** *(text)* - Deprecated +- **type** _(text)_ + Deprecated -* **who** *(integer)* - Deprecated +- **who** _(integer)_ + Deprecated -* **whr** *integer* - Deprecated +- **whr** _integer_ + Deprecated **Example query:** @@ -1446,32 +1447,32 @@ Variables and their values set on hosts at their last reported cf-agent executio **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **NameSpace** *(text)* - [Namespace][Namespaces] within which the variable is set. If no namespace is set then it is set as: `default`. +- **NameSpace** _(text)_ + [Namespace][Namespaces] within which the variable is set. If no namespace is set then it is set as: `default`. -* **Bundle** *(text)* - [Bundle][Bundles] name where the variable is set. +- **Bundle** _(text)_ + [Bundle][Bundles] name where the variable is set. -* **VariableName** *(text)* - Name of the variable. +- **VariableName** _(text)_ + Name of the variable. -* **VariableValue** *(text)* - Variable value serialized to string. - * List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. - * `Data` type is serialized as JSON string. +- **VariableValue** _(text)_ + Variable value serialized to string. + - List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. + - `Data` type is serialized as JSON string. -* **VariableType** *(text)* - Type of the variable. [List][Variables] of supported variable types. +- **VariableType** _(text)_ + Type of the variable. [List][Variables] of supported variable types. -* **MetaTags** *(text[])* - List of [meta tags][Tags for variables, classes, and bundles] set for the variable. +- **MetaTags** _(text[])_ + List of [meta tags][Tags for variables, classes, and bundles] set for the variable. -* **ChangeTimeStamp** *(timestamp)* - Timestamp since when variable is set in its current form. - **Note:** If any of variable attributes change such as its `VariableValue` or `Bundle`, the timestamp will be updated. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp since when variable is set in its current form. + **Note:** If any of variable attributes change such as its `VariableValue` or `Bundle`, the timestamp will be updated. **Example query:** @@ -1525,22 +1526,22 @@ Inventory attributes, these data are using in [List of inventory attributes API] **Columns:** -* **Id** *(integer)* - Auto incremental ID -* **Attribute_name** *(text)* - Attribute name -* **Category** *(text)* *(`Hardware`,`Software`,`Network`, `Security`, `User defined`)* - Attribute category -* **Readonly** *(integer)* *(`0`,`1`)* - Is attribute readonly -* **Type** *(text)* - Type of the attribute. [List][Variables] of supported variable types. -* **convert_function** *(text)* - Convert function. Emp.: `cf_clearSlist` - to transform string like `{"1", "2"}` to `1, 2` -* **keyname** *(text)* - Key name -* **Enabled** *(integer)* *(`0`,`1`)* - Is attribute enabled for the API +- **Id** _(integer)_ + Auto incremental ID +- **Attribute_name** _(text)_ + Attribute name +- **Category** _(text)_ _(`Hardware`,`Software`,`Network`, `Security`, `User defined`)_ + Attribute category +- **Readonly** _(integer)_ _(`0`,`1`)_ + Is attribute readonly +- **Type** _(text)_ + Type of the attribute. [List][Variables] of supported variable types. +- **convert_function** _(text)_ + Convert function. Emp.: `cf_clearSlist` - to transform string like `{"1", "2"}` to `1, 2` +- **keyname** _(text)_ + Key name +- **Enabled** _(integer)_ _(`0`,`1`)_ + Is attribute enabled for the API **Example query:** @@ -1579,39 +1580,39 @@ CFEngine variables set on hosts by CFEngine over period of time. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect data concerning same hosts. -* **ChangeTimeStamp** *(timestamp)* - Timestamp since when variable is set in its current form. - **Note:** The statement if true till present time or newer entry claims otherwise. +- **ChangeTimeStamp** _(timestamp)_ + Timestamp since when variable is set in its current form. + **Note:** The statement if true till present time or newer entry claims otherwise. -* **ChangeOperation** *(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)* - CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. - * `ADD` - stands for introducing a new entry which did not exist before. In this case, new CFEngine variable have been introduced. - * `CHANGE` - stands for changing value or attribute such as `VariableValue` or `MetaTags` have changed. - * `REMOVE` - Variable have not been set. - * `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information is being filtered and will not report any future information about it. +- **ChangeOperation** _(`ADD`,`CHANGE`,`REMOVE`,`UNTRACKED`)_ + CFEngine uses incremental diffs to report it's state. `ChangeOperation` is a diff state describing current entry. + - `ADD` - stands for introducing a new entry which did not exist before. In this case, new CFEngine variable have been introduced. + - `CHANGE` - stands for changing value or attribute such as `VariableValue` or `MetaTags` have changed. + - `REMOVE` - Variable have not been set. + - `UNTRACKED` - CFEngine provides a mechanism for filtering unwanted data from being reported. `UNTRACKED` marker states that information is being filtered and will not report any future information about it. -* **NameSpace** *(text)* - [Namespace][Namespaces] within which the variable is set. If no namespace is set then it is set as: `default`. +- **NameSpace** _(text)_ + [Namespace][Namespaces] within which the variable is set. If no namespace is set then it is set as: `default`. -* **Bundle** *(text)* - [Bundle][Bundles] name where the variable is set. +- **Bundle** _(text)_ + [Bundle][Bundles] name where the variable is set. -* **VariableName** *(text)* - Name of the variable. +- **VariableName** _(text)_ + Name of the variable. -* **VariableValue** *(text)* - Variable value serialized to string. - * List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. - * `Data` type is serialized as JSON string. +- **VariableValue** _(text)_ + Variable value serialized to string. + - List types such as: `slist`, `ilist`, `rlist` are serialized with CFEngine list format: {'value','value'}. + - `Data` type is serialized as JSON string. -* **VariableType** *(text)* - Type of the variable. [List][Variables] of supported variable types. +- **VariableType** _(text)_ + Type of the variable. [List][Variables] of supported variable types. -* **MetaTags** *(text[])* - List of [meta tags][Tags for variables, classes, and bundles] set for the variable. +- **MetaTags** _(text[])_ + List of [meta tags][Tags for variables, classes, and bundles] set for the variable. **Example query:** @@ -1662,25 +1663,26 @@ variablevalue | 67.01 variabletype | string metatags | {monitoring,source=environment} ``` + ## Table: v_hosts V_hosts table contains information about hosts. **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **iscallcollected** *(boolean)* - Is host call collected +- **iscallcollected** _(boolean)_ + Is host call collected -* **LastReportTimeStamp** *(timestamp)* - Timestamp of the most recent successful report collection. +- **LastReportTimeStamp** _(timestamp)_ + Timestamp of the most recent successful report collection. -* **FirstReportTimeStamp** *(timestamp)* - Timestamp when the host reported to the hub for the first time, which - indicate when the host was bootstrapped to the hub. +- **FirstReportTimeStamp** _(timestamp)_ + Timestamp when the host reported to the hub for the first time, which + indicate when the host was bootstrapped to the hub. **Example query:** @@ -1719,26 +1721,26 @@ In this table data are cached what gives a better query performance **Columns:** -* **HostKey** *(text)* - Unique host identifier. All tables can be joined by `HostKey` to connect - data concerning same hosts. +- **HostKey** _(text)_ + Unique host identifier. All tables can be joined by `HostKey` to connect + data concerning same hosts. -* **HostName** *(text)* - Host name locally detected on the host, configurable as `hostIdentifier` - option in [Settings API][Status and settings REST API#Get settings] and - Mission Portal settings UI. +- **HostName** _(text)_ + Host name locally detected on the host, configurable as `hostIdentifier` + option in [Settings API][Status and settings REST API#Get settings] and + Mission Portal settings UI. -* **IPAddress** *(text)* - IP address of the host derived from the lastseen database (this is expected - to be the IP address from which connections come from, beware NAT will cause - multiple hosts to appear to have the same IP address). +- **IPAddress** _(text)_ + IP address of the host derived from the lastseen database (this is expected + to be the IP address from which connections come from, beware NAT will cause + multiple hosts to appear to have the same IP address). -* **LastReportTimeStamp** *(timestamp)* - Timestamp of the most recent successful report collection. +- **LastReportTimeStamp** _(timestamp)_ + Timestamp of the most recent successful report collection. -* **FirstReportTimeStamp** *(timestamp)* - Timestamp when the host reported to the hub for the first time, which - indicate when the host was bootstrapped to the hub. +- **FirstReportTimeStamp** _(timestamp)_ + Timestamp when the host reported to the hub for the first time, which + indicate when the host was bootstrapped to the hub. **Example query:** diff --git a/content/api/enterprise-api-ref/sql-schema/cfmp.markdown b/content/api/enterprise-api-ref/sql-schema/cfmp.markdown index 67d5d289b..14ad1a62c 100644 --- a/content/api/enterprise-api-ref/sql-schema/cfmp.markdown +++ b/content/api/enterprise-api-ref/sql-schema/cfmp.markdown @@ -11,25 +11,25 @@ Information about Mission Portal applications. **Columns:** -* **displayindex** *(integer)* +- **displayindex** _(integer)_ The display order of the app in the Mission Portal menu. -* **filepath** *(text)* +- **filepath** _(text)_ The path of the app module in the application directory. -* **hascontroller** *(integer)* +- **hascontroller** _(integer)_ The flag that indicates whether the app has a controller file or not. -* **icon** *(character varying(50))* +- **icon** _(character varying(50))_ The name of the app icon file in the images directory. -* **meta** *(json)* +- **meta** _(json)_ The JSON object that stores the app metadata, such as name, description, license, etc. -* **showappslist** *(integer)* +- **showappslist** _(integer)_ The flag that indicates whether the app is visible in the Mission Portal menu or not. -* **state** *(integer)* +- **state** _(integer)_ The state of the app, such as 1 or 0. -* **url** *(text)* +- **url** _(text)_ The URL of the app in the Mission Portal. -* **id** *(character varying(100))* +- **id** _(character varying(100))_ The unique identifier of the app, used as the primary key. -* **rbac_id** *(character varying(50))* +- **rbac_id** _(character varying(50))_ The identifier of the RBAC permission that the app requires, may be null. ## Table: astrolabeprofile @@ -38,21 +38,21 @@ Information about Host trees such as who it was created by, who it is shared wit **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The unique identifier of the profile, generated from a sequence. -* **username** *(character varying(50))* +- **username** _(character varying(50))_ The username of the user who created or owns the profile. -* **profileid** *(character varying(50))* +- **profileid** _(character varying(50))_ The name of the profile, such as OS, Services, etc. -* **defaulttree** *(boolean)* +- **defaulttree** _(boolean)_ The flag that indicates whether the profile is the default one for the user or not. -* **globaltree** *(boolean)* +- **globaltree** _(boolean)_ The flag that indicates whether the profile is a global one for all users or not. -* **sharedpermission** *(character varying(50)[])* +- **sharedpermission** _(character varying(50)[])_ The array of usernames that the profile is shared with, may be empty. -* **sharedby** *(character varying(50)[])* +- **sharedby** _(character varying(50)[])_ The array of usernames that shared the profile with the user, may be empty. -* **data** *(json)* +- **data** _(json)_ The JSON object that stores the profile data, such as label, classRegex, children, etc. ## Table: ci_sessions @@ -61,13 +61,13 @@ Information about current sessions. **Columns:** -* **id** *(character varying(128))* +- **id** _(character varying(128))_ The unique identifier of the session, used as the primary key. -* **ip_address** *(character varying(45))* +- **ip_address** _(character varying(45))_ The IP address of the user who initiated the session. -* **timestamp** *(bigint)* +- **timestamp** _(bigint)_ The UNIX timestamp of the last activity of the session. -* **data** *(text)* +- **data** _(text)_ The text data of the session, encoded in base64. ## Table: compliance_score @@ -76,17 +76,17 @@ Compliance reports score. **Columns:** -* **report_id** *(integer)* +- **report_id** _(integer)_ The id of the compliance report that the user has generated. -* **username** *(text)* +- **username** _(text)_ The name of the user who has generated the compliance report. -* **score** *(integer)* +- **score** _(integer)_ The percentage of compliance checks that the user has passed. -* **update_ts** *(timestamp with time zone)* +- **update_ts** _(timestamp with time zone)_ The timestamp of the last update of the compliance report. -* **fail_checks** *(integer)* +- **fail_checks** _(integer)_ The number of compliance checks that the user has failed. -* **total** *(integer)* +- **total** _(integer)_ The total number of compliance checks that the user has performed. ## Table: customization @@ -95,9 +95,9 @@ Stores Mission Portal UI customization config. **Columns:** -* **key** *(character varying)* +- **key** _(character varying)_ The name of the customization option such as logo_on_login, login_text, header_color, etc. -* **value** *(text)* +- **value** _(text)_ The value of the customization option. ## Table: dashboard_alerts @@ -106,51 +106,51 @@ User dashboards alerts status. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The primary key of the dashboard alerts table. -* **ruleid** *(integer)* +- **ruleid** _(integer)_ The id of the rule that triggered the alert. -* **failhosts** *(integer)* +- **failhosts** _(integer)_ The number of hosts that failed the rule. -* **lastcheck** *(integer)* +- **lastcheck** _(integer)_ The timestamp of the last check of the rule. -* **lasteventtime** *(integer)* +- **lasteventtime** _(integer)_ The timestamp of the last event that caused the alert status to change. -* **laststatuschange** *(integer)* +- **laststatuschange** _(integer)_ The timestamp of the last change of the alert status. -* **servertime** *(integer)* +- **servertime** _(integer)_ The timestamp of the server time when the alert was generated. -* **pause** *(integer)* +- **pause** _(integer)_ The timestamp indicating when the alert was paused. -* **paused** *(integer)* +- **paused** _(integer)_ A flag indicating whether the alert was paused by the user or not. -* **name** *(character varying(500))* +- **name** _(character varying(500))_ The name of the alert. -* **severity** *(character varying(10))* +- **severity** _(character varying(10))_ The severity level of the alert, such as high, medium, or low. -* **site_url** *(text)* +- **site_url** _(text)_ The URL of the Mission Portal host where the alert is displayed. -* **status** *(character varying(32))* +- **status** _(character varying(32))_ The status of the alert, such as success, fail, or warning. -* **totalhosts** *(integer)* +- **totalhosts** _(integer)_ The total number of hosts that are affected by the rule. -* **username** *(character varying(50))* +- **username** _(character varying(50))_ The name of the user who created the alert. -* **widgetname** *(character varying(100))* +- **widgetname** _(character varying(100))_ The name of the widget that shows the alert. -* **emailtonotify** *(character varying(100))* +- **emailtonotify** _(character varying(100))_ The email address of the user who will be notified of the alert. -* **reminder** *(integer)* +- **reminder** _(integer)_ The frequency of the reminder email for the alert. -* **widgetid** *(integer)* +- **widgetid** _(integer)_ The id of the widget that shows the alert. -* **hostcontextsprofileid** *(character varying(20))* +- **hostcontextsprofileid** _(character varying(20))_ The id of the host contexts profile that defines the scope of the alert. -* **hostcontexts** *(json)* +- **hostcontexts** _(json)_ A JSON object containing the host contexts that define the scope of the alert. -* **hostcontextspath** *(text)* +- **hostcontextspath** _(text)_ The path of the host contexts that define the scope of the alert. -* **excludedhosts** *(json)* +- **excludedhosts** _(json)_ A JSON object describing hosts that should be excluded from checking the alert. ## Table: dashboard_alerts_script @@ -159,9 +159,9 @@ Association of script with dashboard alert. **Columns:** -* **alert_id** *(integer)* +- **alert_id** _(integer)_ The id of the dashboard alert that is associated with a script. -* **script_id** *(integer)* +- **script_id** _(integer)_ The id of the script that is associated with a dashboard alert. ## Table: dashboard_dashboards @@ -170,17 +170,17 @@ User dashboards and configuration. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The primary key of the dashboard table. -* **name** *(character varying(200))* +- **name** _(character varying(200))_ The name of the dashboard. -* **username** *(character varying(20))* +- **username** _(character varying(20))_ The name of the user who owns the dashboard. -* **public** *(integer)* +- **public** _(integer)_ A flag indicating whether the dashboard is public or private. -* **widgets** *(character varying(200))* +- **widgets** _(character varying(200))_ A comma separated list of widget ids that are displayed on the dashboard. -* **sharedwith** *(jsonb)* +- **sharedwith** _(jsonb)_ A JSON object containing the roles, users, and sharedWithAll flag that determine the sharing settings of the dashboard. ## Table: dashboard_rules @@ -189,35 +189,35 @@ User-defined dashboard alert rules. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ Unique identifier for the dashboard rule. -* **name** *(text)* +- **name** _(text)_ Name of the dashboard rule. -* **description** *(text)* +- **description** _(text)_ Description of the dashboard rule. -* **type** *(character varying(20))* +- **type** _(character varying(20))_ Type of the dashboard rule (e.g., policy, softwareupdate, inventory). -* **username** *(character varying(20))* +- **username** _(character varying(20))_ Username of the user who created the dashboard rule. -* **policyconditions** *(json)* +- **policyconditions** _(json)_ Dashboard rule conditions for checks based on promise outcomes such as KEPT, NOT_KEPT, and REPAIRED. (JSON object) -* **inventoryconditions** *(json)* +- **inventoryconditions** _(json)_ JSON object of conditions for inventory-based dashboard rules. -* **softwareupdateconditions** *(json)* +- **softwareupdateconditions** _(json)_ JSON object of conditions for software update-based dashboard rules. -* **category** *(text)* +- **category** _(text)_ Category assigned to the dashboard rule. -* **severity** *(text)* +- **severity** _(text)_ Severity level assigned to the dashboard rule such as low, medium, high. -* **hostcontexts** *(json)* +- **hostcontexts** _(json)_ JSON object describing the set of hosts the limiting the hosts that should be considered when checking the rule. If not set the condition is checked for against all hosts the user has access to based on RBAC and host reported data. -* **conditionmustbemet** *(boolean)* +- **conditionmustbemet** _(boolean)_ Flag indicating whether conditions must be met for the dashboard rule. -* **customconditions** *(json)* +- **customconditions** _(json)_ Custom dashboard conditions (for widgets), which use SQL queries returning hostkeys of affected hosts (JSON object). -* **filechangedconditions** *(json)* +- **filechangedconditions** _(json)_ File changed conditions for the dashboard rule. -* **export_id** *(text)* +- **export_id** _(text)_ Identifier for exporting dashboard rules. ## Table: dashboard_scripts @@ -226,15 +226,15 @@ Table containing scripts available for association with alerts. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ Unique identifier for the script entry. -* **name** *(text)* +- **name** _(text)_ Name of the script. -* **description** *(text)* +- **description** _(text)_ Description of the script. -* **script_name** *(text)* +- **script_name** _(text)_ Name of the actual script file. -* **type** *(text)* +- **type** _(text)_ Type of the script. (not used) ## Table: dashboard_widgets @@ -243,45 +243,46 @@ User configurations for dashboard widgets. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ Unique identifier for the dashboard widget. -* **name** *(character varying(500))* +- **name** _(character varying(500))_ Name of the dashboard widget. -* **type** *(character varying(20))* +- **type** _(character varying(20))_ Type of the dashboard widget (e.g., inventory, alerts, hostCount). -* **username** *(character varying(50))* +- **username** _(character varying(50))_ Username of the user who configured the dashboard widget. -* **ordering** *(integer)* +- **ordering** _(integer)_ Ordering of the dashboard widget in the dashboard. -* **dashboardid** *(integer)* +- **dashboardid** _(integer)_ Identifier for the associated dashboard. -* **payload** *(jsonb)* +- **payload** _(jsonb)_ JSON payload containing additional configuration for the dashboard widget. + ## Table: eventslog Event logs. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ Unique identifier for the event log entry. -* **username** *(character varying(100))* +- **username** _(character varying(100))_ Username associated with the event log entry. -* **item_id** *(character varying(100))* +- **item_id** _(character varying(100))_ Identifier associated with the item triggering the event (e.g., alert id). -* **item_type** *(character varying)* +- **item_type** _(character varying)_ Type of the item triggering the event (e.g., host, alerts). -* **item_name** *(character varying(500))* +- **item_name** _(character varying(500))_ Name of the item triggering the event. -* **tags** *(character varying(500)[])* +- **tags** _(character varying(500)[])_ Tags associated with the event log entry. -* **time** *(timestamp without time zone)* +- **time** _(timestamp without time zone)_ Timestamp when the event occurred. -* **severity** *(character varying(20))* +- **severity** _(character varying(20))_ Severity level of the event such as low, medium, high. Not all events specify a severity. -* **message** *(text)* +- **message** _(text)_ Detailed message describing the event. -* **status** *(character varying(10))* +- **status** _(character varying(10))_ Status of the event (e.g., triggered, cleared). ## Table: favourite_reports @@ -290,11 +291,11 @@ Table associating favorited reports with users. **Columns:** -* **report_id** *(bigint)* +- **report_id** _(bigint)_ Identifier of the favorite report. -* **username** *(text)* +- **username** _(text)_ Username of the user who marked the report as a favorite. -* **created_at** *(timestamp with time zone)* +- **created_at** _(timestamp with time zone)_ Timestamp indicating when the report was marked as a favorite. ## Table: mail_settings @@ -303,9 +304,9 @@ Global email settings. **Columns:** -* **key** *(character varying)* +- **key** _(character varying)_ Key representing a specific email setting. -* **value** *(text)* +- **value** _(text)_ Value associated with the email setting key. ## Table: pinned_items @@ -314,15 +315,15 @@ Pinned inventory, class, or variable items. **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ Unique identifier for the pinned item. -* **username** *(text)* +- **username** _(text)_ Username of the user who pinned the item. -* **type** *(pinned_type)* +- **type** _(pinned_type)_ Type of the pinned item (e.g., inventory, class, variable). -* **name** *(text)* +- **name** _(text)_ Name of the pinned item. -* **created_at** *(timestamp with time zone)* +- **created_at** _(timestamp with time zone)_ Timestamp indicating when the item was pinned. ## Table: report @@ -331,41 +332,41 @@ Information about saved reports. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The primary key of the report table. -* **username** *(character varying(50))* +- **username** _(character varying(50))_ The name of the user who saved the report. -* **url** *(character varying(500))* +- **url** _(character varying(500))_ The URL of the report. -* **reporttype** *(character varying(50))* +- **reporttype** _(character varying(50))_ The type of the report, such as compliance, inventory, or software update. -* **reportcategory** *(character varying(50))* +- **reportcategory** _(character varying(50))_ The category of the report, such as security, performance, or other. -* **type** *(character varying(50))* +- **type** _(character varying(50))_ The format of the report, such as pdf or csv. -* **readonly** *(integer)* +- **readonly** _(integer)_ A flag indicating whether the report is read-only or editable. -* **is_public** *(integer)* +- **is_public** _(integer)_ A flag indicating whether the report is public or private. -* **can_subscribe** *(integer)* +- **can_subscribe** _(integer)_ A flag indicating whether the report can be subscribed to or not. -* **is_subscribed** *(integer)* +- **is_subscribed** _(integer)_ A flag indicating whether the user is subscribed to the report or not. -* **label** *(character varying(500))* +- **label** _(character varying(500))_ The label of the report. -* **date** *(timestamp without time zone)* +- **date** _(timestamp without time zone)_ The date of the report. -* **params** *(text)* +- **params** _(text)_ The parameters of the report. -* **sharedpermission** *(character varying(50)[])* +- **sharedpermission** _(character varying(50)[])_ A list of permissions that the report has been shared with. -* **sharedby** *(character varying(50)[])* +- **sharedby** _(character varying(50)[])_ A list of users who have shared the report. -* **advancedreportsdata** *(json)* +- **advancedreportsdata** _(json)_ A JSON object containing the advanced reports data. -* **export_id** *(text)* +- **export_id** _(text)_ The export id of the report, used for importing and exporting reports. -* **meta_data** *(jsonb)* +- **meta_data** _(jsonb)_ A JSON object containing the meta data of the report. ## Table: report_schedule @@ -374,45 +375,45 @@ Information about scheduled reports. **Columns:** -* **id** *(character varying(500))* +- **id** _(character varying(500))_ The unique identifier for the scheduled report. -* **reportid** *(integer)* +- **reportid** _(integer)_ The foreign key referencing the associated report. -* **userid** *(character varying(50))* +- **userid** _(character varying(50))_ The user ID associated with the scheduled report. -* **title** *(character varying(500))* +- **title** _(character varying(500))_ The title of the scheduled report. -* **description** *(character varying(500))* +- **description** _(character varying(500))_ The description of the scheduled report. -* **emailfrom** *(character varying(500))* +- **emailfrom** _(character varying(500))_ The email address from which the report is sent. -* **emailto** *(character varying(500))* +- **emailto** _(character varying(500))_ The email address to which the report is sent. -* **enabled** *(integer)* +- **enabled** _(integer)_ Flag indicating whether the scheduled report is enabled. -* **query** *(text)* +- **query** _(text)_ The SQL query that defines the report for the scheduled task. -* **outputtypes** *(character varying(50)[])* +- **outputtypes** _(character varying(50)[])_ Array of output types for the scheduled report. -* **schedule*** *(character varying(500))* +- **schedule\*** _(character varying(500))_ The schedule for running the report. -* **schedulehumanreadabletime** *(character varying(500))* +- **schedulehumanreadabletime** _(character varying(500))_ Human-readable representation of the schedule time. -* **schedulename** *(character varying(500))* +- **schedulename** _(character varying(500))_ The name associated with the schedule. -* **site_url** *(text)* +- **site_url** _(text)_ The URL associated with the scheduled report. -* **hostcontextsprofileid** *(character varying(20))* +- **hostcontextsprofileid** _(character varying(20))_ The profile ID associated with the host contexts. -* **hostcontextspath** *(text)* +- **hostcontextspath** _(text)_ The path associated with the host contexts. -* **hostcontexts** *(json)* +- **hostcontexts** _(json)_ JSON data representing the subset of hosts that the report should be filtered for. If not defined the scheduled report includes all hosts the userid is allowed to see based on RBAC and data reported by the host. -* **scheduledata** *(json)* +- **scheduledata** _(json)_ JSON data containing details about the schedule. -* **excludedhosts** *(json)* +- **excludedhosts** _(json)_ JSON data representing excluded hosts for the scheduled report. -* **skipmailing** *(boolean)* +- **skipmailing** _(boolean)_ Flag indicating whether mailing is skipped for the scheduled report. ## Table: users @@ -421,31 +422,31 @@ User preferences and information about Mission Portal behavior. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The primary key of the user table. -* **username** *(character varying(50))* +- **username** _(character varying(50))_ The unique name of the user. -* **source** *(character varying(20))* +- **source** _(character varying(20))_ The source of the user account, such as internal or external (e.g. LDAP, Active Directory). -* **last_login** *(timestamp without time zone)* +- **last_login** _(timestamp without time zone)_ The timestamp of the last login of the user. -* **remember_code** *(character varying(50))* +- **remember_code** _(character varying(50))_ The code used to remember the user login session. -* **dashboard** *(integer)* +- **dashboard** _(integer)_ The id of the default dashboard for the user. -* **seen_tour** *(smallint)* +- **seen_tour** _(smallint)_ A flag indicating whether the user has seen the tour of the Mission Portal. -* **seen_wizard** *(smallint)* +- **seen_wizard** _(smallint)_ A flag indicating whether the user has seen the wizard of the Mission Portal. -* **never_ask_timezone_change** *(smallint)* +- **never_ask_timezone_change** _(smallint)_ A flag indicating whether the user wants to be asked about changing the timezone. -* **use_browser_time** *(smallint)* +- **use_browser_time** _(smallint)_ A flag indicating whether the user wants to use the browser time or the server time. -* **dark_mode** *(smallint)* +- **dark_mode** _(smallint)_ A flag indicating whether the user prefers the dark mode or the light mode. -* **pinned_items_version** *(smallint)* +- **pinned_items_version** _(smallint)_ This is used to add default pinned items which are added after this version. -* **additional_data** *(jsonb)* +- **additional_data** _(jsonb)_ A JSON object containing additional data about the user preferences and behavior. ## Table: variables_dictionary @@ -454,15 +455,15 @@ Information about reported inventory attributes. **Columns:** -* **id** *(integer)* +- **id** _(integer)_ The unique identifier for the variable in the dictionary. -* **attribute_name** *(character varying(200))* +- **attribute_name** _(character varying(200))_ The name of the attribute represented by the variable. -* **category** *(character varying(200))* +- **category** _(character varying(200))_ The category to which the attribute belongs. -* **readonly** *(integer)* +- **readonly** _(integer)_ Flag indicating whether the attribute is read-only. -* **type** *(character varying(200))* +- **type** _(character varying(200))_ The data type of the attribute such as string, slist, int, real. -* **convert_function** *(character varying(200))* +- **convert_function** _(character varying(200))_ The conversion function applied to the attribute such as cf_clearslist (if any). diff --git a/content/api/enterprise-api-ref/sql-schema/cfsettings.markdown b/content/api/enterprise-api-ref/sql-schema/cfsettings.markdown index 488d4b0d0..ff3062b71 100644 --- a/content/api/enterprise-api-ref/sql-schema/cfsettings.markdown +++ b/content/api/enterprise-api-ref/sql-schema/cfsettings.markdown @@ -11,19 +11,19 @@ Stores system logs about actions performed by users. **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ The unique identifier of audit log event, generated from a sequence. -* **time** *(timestamp without a time zone)* +- **time** _(timestamp without a time zone)_ Time when an event happened. -* **action** *(text)* - What was done (e.g., updated, created, deleted, deployed). -* **object_type** *(text)* +- **action** _(text)_ + What was done (e.g., updated, created, deleted, deployed). +- **object_type** _(text)_ Type of affected object (e.g., user, role, build project). -* **object_id** *(text)* +- **object_id** _(text)_ Identifier of an affected object (e.g. user, role id, build project id), if applicable. -* **details** *(json)* +- **details** _(json)_ More details in the free-json format. -* **ip_address** *(boolean)* +- **ip_address** _(boolean)_ IP address of the user who performed the action. ## Table: build_modules @@ -32,39 +32,39 @@ Information about build modules available from the index (build.cfengine.com). **Columns:** -* **name** *(text)* +- **name** _(text)_ The name of the build module. -* **readme** *(text)* +- **readme** _(text)_ The readme file content of the build module in HTML. -* **description** *(text)* +- **description** _(text)_ The description of the build module. -* **version** *(text)* +- **version** _(text)_ The version of the build module. -* **author** *(jsonb)* +- **author** _(jsonb)_ The author information of the build module as a JSON object with keys such as url, name, image. -* **updated** *(timestamp with time zone)* +- **updated** _(timestamp with time zone)_ The last updated time of the build module. -* **downloads** *(integer)* +- **downloads** _(integer)_ The number of downloads of the build module. -* **repo** *(text)* +- **repo** _(text)_ The repository URL of the build module. -* **documentation** *(text)* +- **documentation** _(text)_ The documentation URL of the build module. -* **website** *(text)* +- **website** _(text)_ The website URL of the build module. -* **subdirectory** *(text)* +- **subdirectory** _(text)_ The subdirectory of the build module in the repository. -* **commit** *(text)* +- **commit** _(text)_ The commit hash of the build module. -* **dependencies** *(jsonb)* +- **dependencies** _(jsonb)_ The dependencies of the build module as a JSON object. -* **tags** *(jsonb)* +- **tags** _(jsonb)_ The tags of the build module as a JSON object. -* **versions** *(jsonb)* +- **versions** _(jsonb)_ The available versions of the build module as a JSON object. -* **latest** *(boolean)* +- **latest** _(boolean)_ A flag indicating whether the build module is the latest version. -* **ts_vector** *(tsvector)** +- **ts_vector** \*(tsvector)\*\* Generated ts_vector column based on id and description. ## Table: build_projects @@ -73,33 +73,33 @@ Build application projects. **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ The unique identifier of the build project, generated from a sequence. -* **repository_url** *(text)* +- **repository_url** _(text)_ The URL of the git repository that contains the build project. -* **branch** *(text)* +- **branch** _(text)_ The branch of the git repository that the build project uses. -* **name** *(text)* +- **name** _(text)_ The name of the build project, derived from the repository URL and branch. -* **authentication_type** *(authentication_types)* +- **authentication_type** _(authentication_types)_ The type of authentication that the build project uses to access the git repository. Must match authentication_types such as password or private_key. -* **username** *(text)* +- **username** _(text)_ The username that the build project uses to access the git repository, if applicable. -* **password** *(text)* +- **password** _(text)_ The password that the build project uses to access the git repository, if applicable. -* **ssh_private_key** *(text)* +- **ssh_private_key** _(text)_ This field is not used. Ref ENT-11330. -* **ssh_key_id** *(integer)* +- **ssh_key_id** _(integer)_ The foreign key that references the ssh_keys table, if applicable. -* **created_at** *(timestamp with time zone)* +- **created_at** _(timestamp with time zone)_ The timestamp of when the build project was created. -* **pushed_at** *(timestamp with time zone)* +- **pushed_at** _(timestamp with time zone)_ The timestamp of when the build project was last pushed to the git repository. -* **is_local** *(boolean)* +- **is_local** _(boolean)_ The flag that indicates whether the build project is local or remote. -* **is_deployed_locally** *(boolean)* +- **is_deployed_locally** _(boolean)_ The flag that indicates whether the build project is deployed locally or not. -* **action** *(text)* +- **action** _(text)_ The action that the build project performs, such as push, pushAndDeploy, localDeploy. ## Table: cfbs_requests @@ -108,17 +108,17 @@ cfbs requests and responses handled by cf-reactor. **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ The unique identifier of the cfbs request, generated from a sequence. -* **request_name** *(text)* +- **request_name** _(text)_ The name of the cfbs request, such as init_project, local_deploy, etc. -* **arguments** *(jsonb)* +- **arguments** _(jsonb)_ The JSONB object that stores the arguments of the cfbs request, such as git, project_id, etc. -* **created_at** *(timestamp with time zone)* +- **created_at** _(timestamp with time zone)_ The timestamp of when the cfbs request was created. -* **finished_at** *(timestamp with time zone)* +- **finished_at** _(timestamp with time zone)_ The timestamp of when the cfbs request was finished, may be null if the request is still in progress. -* **response** *(jsonb)* +- **response** _(jsonb)_ The JSONB object that stores the response of the cfbs request, such as status, details, etc. ## Table: external_roles_map @@ -127,11 +127,11 @@ Map of external directory group to Mission Portal RBAC role for automatic associ **Columns:** -* **external_role** *(text)* +- **external_role** _(text)_ The name of the external directory (LDAP/Active Directory) group. -* **internal_role** *(text)* +- **internal_role** _(text)_ The name of the internal Mission Portal role, such as admin, auditor, or guest. -* **changetimestamp** *(timestamp with time zone)* +- **changetimestamp** _(timestamp with time zone)_ The timestamp of when the mapping was last changed. ## Table: federated_reporting_settings @@ -140,9 +140,9 @@ Federated reporting settings when enabled. **Columns:** -* **key** *(character varying)* +- **key** _(character varying)_ The name of the federated reporting setting, such as enable_as, enable_request_sent, or target_state. -* **value** *(text)* +- **value** _(text)_ The value of the federated reporting setting, such as superhub, 1, or on. ## Table: inventory_aliases @@ -151,9 +151,9 @@ Inventory attributes aliases. **Columns:** -* **inventory_attribute** *(text)* +- **inventory_attribute** _(text)_ The name of the inventory attribute, such as Kernel, Kernel Release, etc. -* **alias** *(text)* +- **alias** _(text)_ The alias of the inventory attribute, such as os type, os kernel, etc. ## Table: keyspendingfordeletion @@ -162,7 +162,7 @@ Keys of deleted hosts yet to be deleted. **Columns:** -* **hostkey** *(text)* +- **hostkey** _(text)_ The key of the host that was deleted from the database but not yet from the ppkeys directory. ## Table: licenseinfo @@ -171,15 +171,15 @@ Information about the currently installed license. **Columns:** -* **expiretimestamp** *(timestamp with time zone)* +- **expiretimestamp** _(timestamp with time zone)_ The timestamp of when the license expires. -* **installtimestamp** *(timestamp with time zone)* +- **installtimestamp** _(timestamp with time zone)_ The timestamp of when the license was installed. -* **organization** *(text)* +- **organization** _(text)_ The name of the organization that owns the license. -* **licensetype** *(text)* +- **licensetype** _(text)_ The type of the license such as Enterprise. -* **licensecount** *(integer)* +- **licensecount** _(integer)_ The number of hosts that the license covers. ## Table: oauth_access_tokens @@ -188,15 +188,15 @@ OAuth access tokens and expiration. **Columns:** -* **access_token** *(character varying(40))* +- **access_token** _(character varying(40))_ The access token that grants access to the OAuth client. -* **client_id** *(character varying(80))* +- **client_id** _(character varying(80))_ The client identifier of the OAuth client that obtained the access token. -* **user_id** *(character varying(255))* +- **user_id** _(character varying(255))_ The user identifier of the user that authorized the access token. -* **expires** *(timestamp without time zone)* +- **expires** _(timestamp without time zone)_ The timestamp of when the access token expires. -* **scope** *(character varying(2000))* +- **scope** _(character varying(2000))_ The scope of access that the access token grants. ## Table: oauth_authorization_codes @@ -205,17 +205,17 @@ OAuth authorizations. **Columns:** -* **authorization_code** *(character varying(40))* +- **authorization_code** _(character varying(40))_ The authorization code that grants access to the OAuth client. -* **client_id** *(character varying(80))* +- **client_id** _(character varying(80))_ The client identifier of the OAuth client that requested the authorization code. -* **user_id** *(character varying(255))* +- **user_id** _(character varying(255))_ The user identifier of the user that authorized the OAuth client. -* **redirect_uri** *(character varying(2000))* +- **redirect_uri** _(character varying(2000))_ The URI that the OAuth client will redirect to after obtaining the authorization code. -* **expires** *(timestamp without time zone)* +- **expires** _(timestamp without time zone)_ The timestamp of when the authorization code expires. -* **scope** *(character varying(2000))* +- **scope** _(character varying(2000))_ The scope of access that the authorization code grants. ## Table: oauth_clients @@ -224,17 +224,17 @@ OAuth clients. **Columns:** -* **client_id** *(character varying(80))* +- **client_id** _(character varying(80))_ The unique identifier of the OAuth client. -* **client_secret** *(character varying(80))* +- **client_secret** _(character varying(80))_ The secret key of the OAuth client. -* **redirect_uri** *(character varying(2000))* +- **redirect_uri** _(character varying(2000))_ The URI that the OAuth client will redirect to after authorization. -* **grant_types** *(character varying(80))* +- **grant_types** _(character varying(80))_ The grant types that the OAuth client supports, such as authorization_code, password, etc. -* **scope** *(character varying(100))* +- **scope** _(character varying(100))_ The scope of access that the OAuth client requests, such as read, write, etc. -* **user_id** *(character varying(80))* +- **user_id** _(character varying(80))_ The user identifier that the OAuth client is associated with. ## Table: oauth_jwt @@ -243,11 +243,11 @@ OAuth JSON Web Tokens. **Columns:** -* **client_id** *(character varying(80))* +- **client_id** _(character varying(80))_ The client identifier of the OAuth client that uses JSON Web Tokens. -* **subject** *(character varying(80))* +- **subject** _(character varying(80))_ The subject of the JSON Web Token, usually the user identifier. -* **public_key** *(character varying(2000))* +- **public_key** _(character varying(2000))_ The public key of the OAuth client that verifies the JSON Web Token signature. ## Table: oauth_refresh_tokens @@ -256,15 +256,15 @@ OAuth token expiration. **Columns:** -* **refresh_token** *(character varying(40))* +- **refresh_token** _(character varying(40))_ The refresh token that can be used to obtain a new access token. -* **client_id** *(character varying(80))* +- **client_id** _(character varying(80))_ The client identifier of the OAuth client that obtained the refresh token. -* **user_id** *(character varying(255))* +- **user_id** _(character varying(255))_ The user identifier of the user that authorized the OAuth client. -* **expires** *(timestamp without time zone)* +- **expires** _(timestamp without time zone)_ The timestamp of when the refresh token expires. -* **scope** *(character varying(2000))* +- **scope** _(character varying(2000))_ The scope of access that the refresh token grants. ## Table: oauth_scopes @@ -273,9 +273,9 @@ OAuth scopes. **Columns:** -* **scope** *(text)* +- **scope** _(text)_ The name of the OAuth scope, such as read, write, etc. -* **is_default** *(boolean)* +- **is_default** _(boolean)_ The flag that indicates whether the OAuth scope is the default scope for new clients. ## Table: rbac_permissions @@ -284,17 +284,17 @@ RBAC permissions. **Columns:** -* **alias** *(character varying(100))* +- **alias** _(character varying(100))_ The unique alias of the RBAC permission, used as the primary key. -* **group** *(character varying(50))* +- **group** _(character varying(50))_ The group that the RBAC permission belongs to, such as Inventory API, Changes API, Events API, Hosts, etc. -* **name** *(character varying(100))* +- **name** _(character varying(100))_ The name of the RBAC permission, such as Get inventory report, Get event list, etc. -* **description** *(character varying(200))* +- **description** _(character varying(200))_ The description of the RBAC permission, explaining what it does and why it is needed. -* **application** *(character varying(50))* +- **application** _(character varying(50))_ The application that the RBAC permission applies to, such as API, Mission Portal, etc. -* **allowed_by_default** *(boolean)* +- **allowed_by_default** _(boolean)_ The flag that indicates whether the RBAC permission is allowed by default for new roles, defaults to false. ## Table: rbac_role_permission @@ -303,9 +303,9 @@ This table associates roles to permissions in a 1-to-many relationship. **Columns:** -* **role_id** *(character varying)* +- **role_id** _(character varying)_ The name of the role that has the permission. -* **permission_alias** *(character varying)* +- **permission_alias** _(character varying)_ The alias of the permission that the role has. ## Table: remote_hubs @@ -314,19 +314,19 @@ Information about federated reporting feeder hubs when federated reporting has b **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ The unique identifier of the remote hub, generated from a sequence. -* **hostkey** *(text)* +- **hostkey** _(text)_ The host key of the remote hub. -* **ui_name** *(character varying(70))* +- **ui_name** _(character varying(70))_ The user-friendly name of the remote hub, must be unique among all remote hubs. -* **api_url** *(text)* +- **api_url** _(text)_ The URL of the remote hub API, used for communication and data transfer. -* **target_state** *(character varying(20))* +- **target_state** _(character varying(20))_ The desired state of the remote hub such as on, paused. -* **transport** *(json)* +- **transport** _(json)_ The JSON object that stores the transport settings of the remote hub with keys such as mode, ssh_user, ssh_host, ssh_pubkey. -* **role** *(character varying(50))* +- **role** _(character varying(50))_ The role of the remote hub, such as feeder or superhub. ## Table: roles @@ -335,17 +335,17 @@ Role definitions that manage host visibility. **Columns:** -* **name** *(text)* +- **name** _(text)_ The name of the role, must be unique and not null. -* **description** *(text)* +- **description** _(text)_ The description of the role. -* **include_rx** *(text)* +- **include_rx** _(text)_ The regular expression that matches classes reported by the host governing what the role can see. -* **exclude_rx** *(text)* +- **exclude_rx** _(text)_ The regular expression that matches classes reported by the host governing what the role cannot see. -* **changetimestamp** *(timestamp with time zone)* +- **changetimestamp** _(timestamp with time zone)_ The timestamp of when the role was last change. -* **is_default** *(boolean)* +- **is_default** _(boolean)_ The boolean flag that indicates whether the role is the default role for new users, defaults to false. ## Table: scheduledreports @@ -354,33 +354,33 @@ Users scheduled reports. **Columns:** -* **username** *(text)* +- **username** _(text)_ The username of the user who scheduled the report. -* **query** *(text)* +- **query** _(text)_ The SQL query that defines the report. -* **query_id** *(text)* +- **query_id** _(text)_ The unique identifier of the query. -* **run_classes** *(text)* +- **run_classes** _(text)_ A CFEngine class expression (without ::) such as (January|February|March|April|May|June|July|August|September|October|November|December).GMT_Hr22.Min50_55 describing when the report should be run. -* **last_executed** *(text)* +- **last_executed** _(text)_ The timestamp of when the report was last executed. -* **email** *(text)* +- **email** _(text)_ The email address of the user who scheduled the report. -* **email_title** *(text)* +- **email_title** _(text)_ The title of the email that contains the report. -* **email_description** *(text)* +- **email_description** _(text)_ The description which is present in the email providing the report. -* **host_include** *(text[])* +- **host_include** _(text[])_ The array of hosts that the report should include. -* **host_exclude** *(text[])* +- **host_exclude** _(text[])_ The array of hosts that the report should exclude (overriding inclusions). -* **already_run** *(boolean)* +- **already_run** _(boolean)_ The boolean flag that indicates whether the report has already run or not. -* **enabled** *(boolean)* +- **enabled** _(boolean)_ The boolean flag that indicates whether the report is enabled or not. -* **output** *(text[])* +- **output** _(text[])_ The array of output formats (csv, pdf) that the report should generate. -* **excludedhosts** *(json)* +- **excludedhosts** _(json)_ The JSON object that stores the hosts that are excluded from the report. ## Table: settings @@ -389,9 +389,9 @@ User settings and preferences for RBAC, host not reporting threshold, collision **Columns:** -* **key** *(text)* +- **key** _(text)_ The Key of the setting. -* **value** *(json)* +- **value** _(json)_ The value of the setting. ## Table: ssh_keys @@ -400,15 +400,15 @@ Generated ssh keys. **Columns:** -* **id** *(bigint)* +- **id** _(bigint)_ The unique identifier of the ssh key, generated from a sequence. -* **public_key** *(text)* +- **public_key** _(text)_ The public key of the ssh key, used for authentication and encryption. -* **private_key** *(text)* +- **private_key** _(text)_ The private key of the ssh key, used for decryption and signing. -* **generated_at** *(timestamp with time zone)* +- **generated_at** _(timestamp with time zone)_ The timestamp of when the ssh key was generated, defaults to the current time. -* **generated_by** *(text)* +- **generated_by** _(text)_ The username of the user who generated the ssh key. ## Table: users @@ -417,25 +417,25 @@ User settings (name, email, password, timezone, provenance) and roles associated **Columns:** -* **username** *(text)* +- **username** _(text)_ The username of the user. -* **password** *(text)* +- **password** _(text)_ The hashed password of the user. -* **salt** *(text)* +- **salt** _(text)_ The salt used to hash the password of the user. -* **name** *(text)* +- **name** _(text)_ The name of the user. -* **email** *(text)* +- **email** _(text)_ The email address of the user. -* **external** *(boolean)* +- **external** _(boolean)_ The boolean flag that indicates whether the user is an external user or not, defaults to false. -* **active** *(boolean)* +- **active** _(boolean)_ The boolean flag that indicates whether the user is active or not, defaults to false. -* **roles** *(text[])* +- **roles** _(text[])_ The array of roles that the user has, defaults to an empty array. -* **time_zone** *(text)* +- **time_zone** _(text)_ The timestamp of when the user settings were last changed. -* **changetimestamp** *(timestamp with time zone)* +- **changetimestamp** _(timestamp with time zone)_ The time zone of the user, defaults to Etc/GMT+0. ## Table: setup_codes @@ -444,19 +444,19 @@ Stores setup codes used to complete hub setup. **Columns:** -* **id** *(serial)* +- **id** _(serial)_ Unique auto-incrementing identifier. -* **code** *(char(6))* +- **code** _(char(6))_ Six-character code. -* **created_at** *(timestamp with time zone)* +- **created_at** _(timestamp with time zone)_ Timestamp indicating when the setup code was created, defaults to NOW(). -* **expires_at** *(timestamp with time zone)* +- **expires_at** _(timestamp with time zone)_ Timestamp indicating when the setup code will expire. -* **attempts** *(integer)* +- **attempts** _(integer)_ Number of attempts made to use the setup code, defaults to 0. -* **is_revoked** *(boolean)* +- **is_revoked** _(boolean)_ Indicates whether the setup code has been revoked before expiration, defaults to false. -* **is_used** *(boolean)* +- **is_used** _(boolean)_ Indicates whether the setup code has been successfully used, defaults to false. -* **session_id** *(varchar(64))* +- **session_id** _(varchar(64))_ Session identifier linking the setup code to a session, can be null. diff --git a/content/api/enterprise-api-ref/ssh-keys-api.markdown b/content/api/enterprise-api-ref/ssh-keys-api.markdown index f9fd80cca..1c022b40a 100644 --- a/content/api/enterprise-api-ref/ssh-keys-api.markdown +++ b/content/api/enterprise-api-ref/ssh-keys-api.markdown @@ -35,10 +35,10 @@ HTTP 200 Ok **Responses:** -| HTTP response code | Description | -|--------|-------------| -| 200 OK | SSH key successfully created | -| 500 Internal server error | Internal server error | +| HTTP response code | Description | +| ------------------------- | ---------------------------- | +| 200 OK | SSH key successfully created | +| 500 Internal server error | Internal server error | ### Get SSH keys list @@ -76,9 +76,9 @@ HTTP 200 OK **Responses:** -| HTTP response code | Description | -|--------|-------------| -| 200 Ok | Successful response | +| HTTP response code | Description | +| ------------------------- | --------------------- | +| 200 Ok | Successful response | | 500 Internal server error | Internal server error | ### Get SSH key @@ -89,7 +89,7 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ SSH key ID. Required. **Example request (curl):** @@ -114,10 +114,10 @@ HTTP 200 OK **Responses:** -| HTTP response code | Description | -|--------|-------------| -| 200 Ok | Successful response | -| 404 Not found | SSH key not found | +| HTTP response code | Description | +| ------------------------- | --------------------- | +| 200 Ok | Successful response | +| 404 Not found | SSH key not found | | 500 Internal server error | Internal server error | ### Delete SSH key @@ -128,7 +128,7 @@ HTTP 200 OK **Parameters:** -* **id** *(integer)* +- **id** _(integer)_ SSH key ID. Required. **Example request (curl):** @@ -147,8 +147,8 @@ HTTP 204 No content **Responses:** -| HTTP response code | Description | -|--------|-------------| -| 204 No content | SSH key successfully deleted | -| 404 Not found | SSH key not found | -| 500 Internal server error | Internal server error | +| HTTP response code | Description | +| ------------------------- | ---------------------------- | +| 204 No content | SSH key successfully deleted | +| 404 Not found | SSH key not found | +| 500 Internal server error | Internal server error | diff --git a/content/api/enterprise-api-ref/status-settings.markdown b/content/api/enterprise-api-ref/status-settings.markdown index b63a4ba67..4a8bc9686 100644 --- a/content/api/enterprise-api-ref/status-settings.markdown +++ b/content/api/enterprise-api-ref/status-settings.markdown @@ -43,26 +43,26 @@ REST API for managing settings, checking hub status. **Output:** -* **apiName** - Human-friendly API name. -* **apiVersion** - API version string. -* **enterpriseVersion** - Version of the CFEngine Enterprise build. -* **uiVersion** - The internal build number of the Enterprise UI. -* **coreVersion** - The version of CFEngine Core (Community) the Enterprise version was built against. -* **authenticated** *("internal", "external")* - Whether the request was authenticated using the internal users table or an external source. -* **license.expires** - Time when the license expires. -* **license.owner** - The name of the license owner. -* **license.granted** - Host number capacity granted by the license. -* **license.licenseType** - License description. +- **apiName** + Human-friendly API name. +- **apiVersion** + API version string. +- **enterpriseVersion** + Version of the CFEngine Enterprise build. +- **uiVersion** + The internal build number of the Enterprise UI. +- **coreVersion** + The version of CFEngine Core (Community) the Enterprise version was built against. +- **authenticated** _("internal", "external")_ + Whether the request was authenticated using the internal users table or an external source. +- **license.expires** + Time when the license expires. +- **license.owner** + The name of the license owner. +- **license.granted** + Host number capacity granted by the license. +- **license.licenseType** + License description. **Example usage:** `Checking status` @@ -118,33 +118,33 @@ administrator. **Fields**: -* **rbacEnabled** *(boolean)* - Whether RBAC is applied to requests. -* **hostIdentifier** *(string)* - The identfying string for hosts, such as name or IP. -* **ldapEnabled** *(boolean)* - Whether external authentication is activated. -* **logLevel** *("emergency", "alert", "critical", "error", "warning", "notice", "info", "debug")* - Syslog filter specifying the severity level at which messages produced by the API should be emitted to syslog and apache.log. (default: error). -* **blueHostHorizon** *(900)* - Threshold in minutes that hosts are unreachable before they are considered a health issue. -* **sameHostsNumberOfRuns** *(integer)* - Number of samples used to identify a duplicate identity. Default value is 3. -* **enforce2FA** *(boolean)* - Determines if two-factor authentication (2FA) is mandatory for all users. - If set to `true`, users must enable 2FA; otherwise, they will be locked out within 48 hours after the first login. - Default value: `false` -* **minPasswordLength** *(integer)* - Sets the minimum required length for user passwords. - The value represents the number of characters. - Default value: `8` -* **passwordComplexity** *(integer)* - Defines the level of password complexity required. - The range is from 0 to 4, where zero turns of the password complexity check and four turns on the maximum level. - Default value: `3` -* **passwordExpirationAfterResetHours** *(integer)* - Specifies the number of hours after which a password must expire following a reset. - Default value: `48` +- **rbacEnabled** _(boolean)_ + Whether RBAC is applied to requests. +- **hostIdentifier** _(string)_ + The identfying string for hosts, such as name or IP. +- **ldapEnabled** _(boolean)_ + Whether external authentication is activated. +- **logLevel** _("emergency", "alert", "critical", "error", "warning", "notice", "info", "debug")_ + Syslog filter specifying the severity level at which messages produced by the API should be emitted to syslog and apache.log. (default: error). +- **blueHostHorizon** _(900)_ + Threshold in minutes that hosts are unreachable before they are considered a health issue. +- **sameHostsNumberOfRuns** _(integer)_ + Number of samples used to identify a duplicate identity. Default value is 3. +- **enforce2FA** _(boolean)_ + Determines if two-factor authentication (2FA) is mandatory for all users. + If set to `true`, users must enable 2FA; otherwise, they will be locked out within 48 hours after the first login. + Default value: `false` +- **minPasswordLength** _(integer)_ + Sets the minimum required length for user passwords. + The value represents the number of characters. + Default value: `8` +- **passwordComplexity** _(integer)_ + Defines the level of password complexity required. + The range is from 0 to 4, where zero turns of the password complexity check and four turns on the maximum level. + Default value: `3` +- **passwordExpirationAfterResetHours** _(integer)_ + Specifies the number of hours after which a password must expire following a reset. + Default value: `48` **Example Request Body:** diff --git a/content/api/enterprise-api-ref/two-factor-authentication.markdown b/content/api/enterprise-api-ref/two-factor-authentication.markdown index fbf5d7fbf..47dcf1ee4 100644 --- a/content/api/enterprise-api-ref/two-factor-authentication.markdown +++ b/content/api/enterprise-api-ref/two-factor-authentication.markdown @@ -2,6 +2,7 @@ layout: default title: Two-factor authentication API --- + The Two-factor authentication API enables users to add an extra layer of security to their accounts by requiring a TOTP (time-based one-time password) in addition to their primary credentials. @@ -47,25 +48,25 @@ HTTP 200 Ok **Output:** -* **secret** +- **secret** The secret key used to generate the one-time password (OTP) -* **2faUrl** +- **2faUrl** The URL that can be converted into QR code and scanned with an authenticator app to set up two-factor authentication -* **algorithm** +- **algorithm** The cryptographic algorithm used to generate the OTP -* **digits** +- **digits** The number of digits in the generated OTP code -* **period** +- **period** The time period in seconds for which the OTP code is valid -* **issuer** +- **issuer** The name of the service that is providing the two-factor authentication -* **holder** +- **holder** The username for whom the two-factor authentication is being configured **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------------------| +| ------------------------- | -------------------------------------- | | 200 OK | 2FA configuration successfully created | | 500 Internal server error | Internal server error | @@ -77,7 +78,7 @@ HTTP 200 Ok **Parameters:** -* **code** *(string)* +- **code** _(string)_ 6-digit code from the authentication application **Example request (curl):** @@ -99,7 +100,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|-----------------------------| +| ------------------------- | --------------------------- | | 200 OK | 2FA successfully configured | | 400 Bad request | 2FA verification failed. | | 500 Internal server error | Internal server error | @@ -112,7 +113,7 @@ HTTP 200 Ok **Headers:** -* **Cf-2FA-Token** *(string)* +- **Cf-2FA-Token** _(string)_ 6-digit code from the authentication application **Example request (curl):** @@ -134,7 +135,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------------------| +| ------------------------- | -------------------------------------- | | 200 OK | 2FA successfully disabled | | 401 Unauthorized | Invalid two-factor authentication code | | 409 Conflict | 2FA is not enabled for this user | @@ -168,7 +169,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------------------| +| ------------------------- | -------------------------------------- | | 200 OK | 2FA successfully disabled | | 401 Unauthorized | Invalid two-factor authentication code | | 409 Conflict | 2FA is not enabled for this user | @@ -186,7 +187,7 @@ verification, you will not need to provide the authorization code from the authe **Parameters:** -* **code** *(string)* +- **code** _(string)_ 6-digit code from the authentication application **Example request (curl):** @@ -208,7 +209,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------------| +| ------------------------- | -------------------------------- | | 200 OK | 2FA successfully verified | | 409 Conflict | 2FA is not enabled for this user | | 500 Internal server error | Internal server error | @@ -242,7 +243,7 @@ HTTP 200 Ok **Responses:** | HTTP response code | Description | -|---------------------------|----------------------------------| +| ------------------------- | -------------------------------- | | 200 OK | 2FA successfully checked | | 409 Conflict | 2FA is not enabled for this user | | 500 Internal server error | Internal server error | diff --git a/content/api/enterprise-api-ref/users-rbac.markdown b/content/api/enterprise-api-ref/users-rbac.markdown index 022d6e62c..7f1439587 100644 --- a/content/api/enterprise-api-ref/users-rbac.markdown +++ b/content/api/enterprise-api-ref/users-rbac.markdown @@ -16,10 +16,10 @@ API call allowed only for administrator. **Parameters:** -* **id** *(regex string)* - Regular expression for filtering usernames. -* **external** *('true', 'false')* - Returns only internal users (false) or only external (true), or all if not specified. +- **id** _(regex string)_ + Regular expression for filtering usernames. +- **external** _('true', 'false')_ + Returns only internal users (false) or only external (true), or all if not specified. **Example response:** @@ -67,16 +67,16 @@ API call allowed only for administrator. **Output:** -* **id** - User name. -* **email** - Email address. -* **roles** - List of assigned RBAC roles. -* **external** - Is user from external source (LDAP/AD). -* **two_factor_enabled** - If a user has enabled two-factor authentication +- **id** + User name. +- **email** + Email address. +- **roles** + List of assigned RBAC roles. +- **external** + Is user from external source (LDAP/AD). +- **two_factor_enabled** + If a user has enabled two-factor authentication **Example usage:** `Example: Listing users` @@ -117,18 +117,18 @@ API call allowed only for administrator. **Output:** -* **id** - User name. -* **email** - Email address. -* **roles** - List of assigned RBAC roles. -* **external** - Is user from external source (LDAP/AD). -* **time_zone** - Time zone -* **two_factor_enabled** - If a user has enabled two-factor authentication +- **id** + User name. +- **email** + Email address. +- **roles** + List of assigned RBAC roles. +- **external** + Is user from external source (LDAP/AD). +- **time_zone** + Time zone +- **two_factor_enabled** + If a user has enabled two-factor authentication **Example usage:** `Example: Retrieving a user` @@ -140,16 +140,16 @@ API call allowed only for administrator. **Parameters:** -* **username** *(string)* - User name -* **password** *(string)* - User password -* **email** *(string)* - User email -* **roles** *(array)* - User roles, emp: `["admin", "test"]` -* **time_zone** *(string)* - Time zone +- **username** _(string)_ + User name +- **password** _(string)_ + User password +- **email** _(string)_ + User email +- **roles** _(array)_ + User roles, emp: `["admin", "test"]` +- **time_zone** _(string)_ + Time zone Create a new user. API call allowed only for administrator. @@ -178,16 +178,16 @@ API call allowed only for administrator. **Parameters:** -* **username** *(string)* - User name -* **password** *(string)* - User password -* **email** *(string)* - User email -* **roles** *(array)* - User roles, emp: `["admin", "test"]` -* **time_zone** *(string)* - Time zone +- **username** _(string)_ + User name +- **password** _(string)_ + User password +- **email** _(string)_ + User email +- **roles** _(array)_ + User roles, emp: `["admin", "test"]` +- **time_zone** _(string)_ + Time zone **Example Request Body:** @@ -253,14 +253,14 @@ API call allowed only for administrator. **Output:** -* **id** - Unique role name. -* **description** - Role description. -* **includeContext** - Permit access to hosts that have **class set**. -* **excludeContext** - Permit access to hosts that have **class not set**. +- **id** + Unique role name. +- **description** + Role description. +- **includeContext** + Permit access to hosts that have **class set**. +- **excludeContext** + Permit access to hosts that have **class not set**. ## Get RBAC role @@ -293,14 +293,14 @@ API call allowed only for administrator. **Output:** -* **id** - Unique role name. -* **description** - Role description. -* **includeContext** - Permit access to hosts that have **class set**. -* **excludeContext** - Permit access to hosts that have **class not set**. +- **id** + Unique role name. +- **description** + Role description. +- **includeContext** + Permit access to hosts that have **class set**. +- **excludeContext** + Permit access to hosts that have **class not set**. ## Create RBAC role @@ -313,12 +313,12 @@ API call allowed only for administrator. **Fields:** -* **description** - Role description. -* **includeContext** - Permit access to hosts that have **class set**. -* **excludeContext** - Permit access to hosts that have **class not set**. +- **description** + Role description. +- **includeContext** + Permit access to hosts that have **class set**. +- **excludeContext** + Permit access to hosts that have **class not set**. **Example Request Body:** @@ -341,12 +341,12 @@ API call allowed only for administrator. **Fields:** -* **description** - Role description. -* **includeContext** - Permit access to hosts that have **class set**. -* **excludeContext** - Permit access to hosts that have **class not set** +- **description** + Role description. +- **includeContext** + Permit access to hosts that have **class set**. +- **excludeContext** + Permit access to hosts that have **class not set** **Example Request Body:** diff --git a/content/api/enterprise-api-ref/vcs-settings.markdown b/content/api/enterprise-api-ref/vcs-settings.markdown index 9fc56f8c7..6414c884f 100644 --- a/content/api/enterprise-api-ref/vcs-settings.markdown +++ b/content/api/enterprise-api-ref/vcs-settings.markdown @@ -2,6 +2,7 @@ layout: default title: VCS settings API --- + VCS API for managing version control repository settings. ## Get VCS settings @@ -51,21 +52,21 @@ curl -k --user : \ **Parameters:** -* **vscType** *(string)* +- **vscType** _(string)_ VCS type. Allowed values: `GIT`, `GIT_CFBS`. Default value: `GIT` -* **gitServer** *(string)* - Git repository URL `Emp: https://github.com/cfengine/masterfiles.git`. Required parameter. -* **gitRefspec** *(string)* - The Git refspec to checkout. It can be a branch name, a tag name, a commit hash or a partial hash. Required parameter. -* **projectSubdirectory** *(string)* - Subdirectory inside Git repository where the project is located. - Optional parameter. -* **gitUsername** *(string)* - Git username for authentication, not needed for public repositories. -* **gitPassword** *(string)* - Git password or token for authentication, not needed for public repositories. -* **gitPrivateKey** *(string)* - Git private key raw content for authentication. +- **gitServer** _(string)_ + Git repository URL `Emp: https://github.com/cfengine/masterfiles.git`. Required parameter. +- **gitRefspec** _(string)_ + The Git refspec to checkout. It can be a branch name, a tag name, a commit hash or a partial hash. Required parameter. +- **projectSubdirectory** _(string)_ + Subdirectory inside Git repository where the project is located. + Optional parameter. +- **gitUsername** _(string)_ + Git username for authentication, not needed for public repositories. +- **gitPassword** _(string)_ + Git password or token for authentication, not needed for public repositories. +- **gitPrivateKey** _(string)_ + Git private key raw content for authentication. **Example request (curl):** @@ -100,5 +101,5 @@ curl -k --user : \ ## History -* `vscType` parameter added in 3.19.0, 3.18.1 -* `projectSubdirectory` parameter added in 3.21.7, 3.24.2, 3.26.0 +- `vscType` parameter added in 3.19.0, 3.18.1 +- `projectSubdirectory` parameter added in 3.21.7, 3.24.2, 3.26.0 diff --git a/content/api/enterprise-api-ref/web-rbac.markdown b/content/api/enterprise-api-ref/web-rbac.markdown index 25c5387a5..1d6d3ab03 100644 --- a/content/api/enterprise-api-ref/web-rbac.markdown +++ b/content/api/enterprise-api-ref/web-rbac.markdown @@ -2,6 +2,7 @@ layout: default title: Web RBAC API --- + Web RBAC API for managing role based access control settings. ## Get all permissions list @@ -51,18 +52,18 @@ curl -k --user : \ **Output:** -* **alias** *(string)* - Alias (ID) of a permission -* **group** *(string)* - Group of a permission. -* **name** *(string)* - Name of a permission. -* **description** *(string)* - Description of a permission. -* **application** *(string)* - Application of a permission. Allowed values: `API`, `Mission portal` -* **allowed_by_default** *(boolean)* - Permission allowed by default. New role will be able to perform allowed by default actions. +- **alias** _(string)_ + Alias (ID) of a permission +- **group** _(string)_ + Group of a permission. +- **name** _(string)_ + Name of a permission. +- **description** _(string)_ + Description of a permission. +- **application** _(string)_ + Application of a permission. Allowed values: `API`, `Mission portal` +- **allowed_by_default** _(boolean)_ + Permission allowed by default. New role will be able to perform allowed by default actions. ## Get current user permissions @@ -79,6 +80,7 @@ curl -k --user : \ ``` **Example response:** + ``` [ { @@ -116,8 +118,8 @@ curl -k --user : \ **Parameters:** -* **role_name** *(string)* - Role name +- **role_name** _(string)_ + Role name **Example request (curl):** @@ -168,11 +170,11 @@ Assign new permission to role. Permissions will be added to existing permission **Parameters:** -* **role_name** *(string)* - Role name +- **role_name** _(string)_ + Role name -* **alias** *(array)* - Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. +- **alias** _(array)_ + Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. **Example request (curl):** @@ -200,11 +202,11 @@ Assign permission to role. New permissions replace existing. **Parameters:** -* **role_name** *(string)* - Role name +- **role_name** _(string)_ + Role name -* **alias** *(array)* - Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. +- **alias** _(array)_ + Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. **Example request (curl):** @@ -230,11 +232,11 @@ HTTP 201 Created **Parameters:** -* **role_name** *(string)* - Role name +- **role_name** _(string)_ + Role name -* **alias** *(array)* - Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. +- **alias** _(array)_ + Array of permission aliases `Emp: ["Inventory.post", "VariablesDictionary.get"]`. Required parameter. **Example request (curl):** diff --git a/content/enterprise-cfengine-guide/install-get-started.markdown b/content/enterprise-cfengine-guide/install-get-started.markdown index fcf101042..27c03163d 100644 --- a/content/enterprise-cfengine-guide/install-get-started.markdown +++ b/content/enterprise-cfengine-guide/install-get-started.markdown @@ -10,8 +10,8 @@ Delete "Enterprise Install and Get Started" https://docs.google.com/document/d/1CeRR8cuMtrrr0X27gzVzP2ndiU0HuHvo7dJT2vIWfp0/edit#heading=h.978wiks7ber1 --> -* [Installation][Install and Get Started#Installation] -* [Post-install configuration][Install and Get Started#Post-install configuration] +- [Installation][Install and Get Started#Installation] +- [Post-install configuration][Install and Get Started#Post-install configuration] ## Installation @@ -29,7 +29,7 @@ will be provided with the key. For Enterprise 3.6 local mail relay is used, and it is assumed the server has a proper mail setup. -The default FROM email for all emails sent from the Mission Portal is ```admin@organization.com```. This can be changed on the CFE Server in ```/var/cfengine/httpd/htdocs/application/config/appsettings.php:$config['appemail']```. +The default FROM email for all emails sent from the Mission Portal is `admin@organization.com`. This can be changed on the CFE Server in `/var/cfengine/httpd/htdocs/application/config/appsettings.php:$config['appemail']`. ### Version your policies diff --git a/content/examples/_index.markdown b/content/examples/_index.markdown index 94fce17d9..a87842b8e 100644 --- a/content/examples/_index.markdown +++ b/content/examples/_index.markdown @@ -6,30 +6,30 @@ sorting: 60 ## Links to examples -* [Example snippets][Example snippets]: This section is divided into topical areas and includes many examples of policy and promises. Each of the snippets can be easily copied or downloaded to a policy server and used as is. +- [Example snippets][Example snippets]: This section is divided into topical areas and includes many examples of policy and promises. Each of the snippets can be easily copied or downloaded to a policy server and used as is. **Note:** CFEngine also includes a small set of examples by default, which can be found in `/var/cfengine/share/doc/examples`. -* [Enterprise API examples][Enterprise API examples] -* [Tutorials][Tutorials] +- [Enterprise API examples][Enterprise API examples] +- [Tutorials][Tutorials] See also: -* [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] - * ["Hello world" policy example][Examples and tutorials#"Hello world" policy example] - * [Activate a bundle manually][Examples and tutorials#Activate a bundle manually] - * [Make the example stand alone][Examples and tutorials#Make the example stand alone] - * [Make the example an executable script][Examples and tutorials#Make the example an executable script] - * [Integrating the example into your main policy][Examples and tutorials#Integrating the example into your main policy] +- [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] + - ["Hello world" policy example][Examples and tutorials#"Hello world" policy example] + - [Activate a bundle manually][Examples and tutorials#Activate a bundle manually] + - [Make the example stand alone][Examples and tutorials#Make the example stand alone] + - [Make the example an executable script][Examples and tutorials#Make the example an executable script] + - [Integrating the example into your main policy][Examples and tutorials#Integrating the example into your main policy] ## Tutorial for running examples In this tutorial, you will perform the following: -* Create a simple "Hello World!" example policy file -* Make the example a standalone policy -* Make the example an executable script -* Add the example to the main policy file (`promises.cf`) +- Create a simple "Hello World!" example policy file +- Make the example a standalone policy +- Make the example an executable script +- Add the example to the main policy file (`promises.cf`) **Note** if your CFEngine administrator has enabled continuous deployment of the policy from a Version control System, your changes may be overwritten! @@ -41,10 +41,10 @@ intent. Bundles allow related promises to be grouped together, as illustrated in Following these steps, you will login to your policy server via the SSH protocol, use the vi command line editor to create a policy file named hello_world.cf, and create a bundle that calls a promise to display some text. 1. Log into a running server machine using ssh (PuTTY may be used if using Windows). -2. Type ```sudo su``` for super user (enter your password if prompted). -3. To get to the __masterfiles__ directory, type ```cd /var/cfengine/masterfiles```. -4. Create the file with the command: ```vi hello_world.cf ``` -5. In the vi editor, enter ```i``` for "Insert" and enter the following content (ie. copy and paste from a text editor): +2. Type `sudo su` for super user (enter your password if prompted). +3. To get to the **masterfiles** directory, type `cd /var/cfengine/masterfiles`. +4. Create the file with the command: `vi hello_world.cf ` +5. In the vi editor, enter `i` for "Insert" and enter the following content (ie. copy and paste from a text editor): ```cf3 {file="hello_world.cf"} bundle agent hello_world { @@ -54,8 +54,8 @@ Following these steps, you will login to your policy server via the SSH protocol } ``` 6. Exit the "Insert" mode by pressing the "esc" button. This will return to the command prompt. -7. Save the changes to the file by typing ```:w``` then "Enter". -8. Exit vi by typing ```:q``` then "Enter". +7. Save the changes to the file by typing `:w` then "Enter". +8. Exit vi by typing `:q` then "Enter". In the policy file above, we have defined an **agent bundle** named `hello_world`. Agent bundles are only evaluated by **cf-agent**, the [agent component][cf-agent] of CFEngine. @@ -99,10 +99,10 @@ Instead of specifying the bundle sequence on the command line (as it was above), control][Components#Common control] section can be added to the policy file. The **body common control** refers to those promises that are hard-coded into all CFEngine components and therefore affect the behavior of all components. Note that only - one `body common control` is allowed per agent activation. +one `body common control` is allowed per agent activation. -Go back into vi by typing "vi" at the prompt. Then type ```i``` to insert - __body common control__ to `hello_world.cf`. Place it above __bundle agent hello_world__, as +Go back into vi by typing "vi" at the prompt. Then type `i` to insert +**body common control** to `hello_world.cf`. Place it above **bundle agent hello_world**, as shown in the following example: ```cf3 {file="hello_world.cf"} @@ -119,8 +119,8 @@ bundle agent hello_world } ``` -Now press "esc" to exit the "Insert" mode, then type ```:w``` to save the file changes and "Enter". -Exit vi by typing ```:q``` then "Enter." This will return to the prompt. +Now press "esc" to exit the "Insert" mode, then type `:w` to save the file changes and "Enter". +Exit vi by typing `:q` then "Enter." This will return to the prompt. Execute the following command: @@ -146,14 +146,14 @@ body common control ### Make the example an executable script -Add the ```#!``` marker ("shebang") to `hello_world.cf` in order to invoke CFEngine policy as an executable script: -Again type "vi" then "Enter" then ```i``` to insert the following: +Add the `#!` marker ("shebang") to `hello_world.cf` in order to invoke CFEngine policy as an executable script: +Again type "vi" then "Enter" then `i` to insert the following: ```cf3 #!/var/cfengine/bin/cf-agent --no-lock ``` -Add it before __body common control__, as shown below: +Add it before **body common control**, as shown below: ```cf3 {file="hello_world.cf"} #!/var/cfengine/bin/cf-agent --no-lock @@ -170,8 +170,8 @@ bundle agent hello_world } ``` -Now exit "Insert" mode by pressing "esc". Save file changes by typing ```:w``` then "Enter" -then exit vi by typing ```:q``` then "Enter". This will return to the prompt. +Now exit "Insert" mode by pressing "esc". Save file changes by typing `:w` then "Enter" +then exit vi by typing `:q` then "Enter". This will return to the prompt. Make the policy file executable: @@ -197,7 +197,7 @@ doing the following on your policy server: 1. Ensure the example is located in `/var/cfengine/masterfiles`. 2. If the example contains a `body common control` section, delete it. That -section will look something like this: + section will look something like this: ```cf3 body common control @@ -217,41 +217,41 @@ file `/var/cfengine/masterfiles/promises.cf`and then remove the control body from the example. 3. Insert the example's bundle name in the `bundlesequence` section - of the main policy file `/var/cfengine/masterfiles/promises.cf`: + of the main policy file `/var/cfengine/masterfiles/promises.cf`: - ```cf3 - bundlesequence => { - ... - "hello_world", - ... - }; - ``` + ```cf3 + bundlesequence => { + ... + "hello_world", + ... + }; + ``` 4. Insert the policy file name in the [`inputs`][Components#inputs] section of the main policy file - `/var/cfengine/masterfiles/promises.cf`: + `/var/cfengine/masterfiles/promises.cf`: - ```cf3 - inputs => { - ... - "hello_world.cf", - ... - }; - ``` + ```cf3 + inputs => { + ... + "hello_world.cf", + ... + }; + ``` 5. You must also remove any inputs section from the example that includes the external library: - ```cf3 - inputs => { - "libraries/cfengine_stdlib.cf" - }; - ``` + ```cf3 + inputs => { + "libraries/cfengine_stdlib.cf" + }; + ``` - This is necessary, since `cfengine_stdlib.cf` is already included - in the inputs section of the master policy. + This is necessary, since `cfengine_stdlib.cf` is already included + in the inputs section of the master policy. 6. The example policy will now be executed every five minutes along with the rest -of your main policy. + of your main policy. **Notes:** You may have to fill the example with data before it will work. For example, the LDAP query in `active_directory.cf` needs a domain name. diff --git a/content/examples/example-snippets/_index.markdown b/content/examples/example-snippets/_index.markdown index 47ba78fa3..9f03b0191 100644 --- a/content/examples/example-snippets/_index.markdown +++ b/content/examples/example-snippets/_index.markdown @@ -4,18 +4,18 @@ title: Example snippets sorting: 1 --- -* [General examples][General examples] -* [Administration examples][Administration examples] -* [Measuring examples][Measuring examples] -* [Software administration examples][Software administration examples] -* [Commands, scripts, and execution examples][Commands, scripts, and execution examples] -* [File and directory examples][File and directory examples] -* [File template examples][File template examples] -* [Database examples][Database examples] -* [Network examples][Network examples] -* [System security examples][System security examples] -* [System information examples][System information examples] -* [System administration examples][System administration examples] -* [System file examples][System file examples] -* [Windows registry examples][Windows registry examples] -* [User management][User management examples] +- [General examples][General examples] +- [Administration examples][Administration examples] +- [Measuring examples][Measuring examples] +- [Software administration examples][Software administration examples] +- [Commands, scripts, and execution examples][Commands, scripts, and execution examples] +- [File and directory examples][File and directory examples] +- [File template examples][File template examples] +- [Database examples][Database examples] +- [Network examples][Network examples] +- [System security examples][System security examples] +- [System information examples][System information examples] +- [System administration examples][System administration examples] +- [System file examples][System file examples] +- [Windows registry examples][Windows registry examples] +- [User management][User management examples] diff --git a/content/examples/example-snippets/basic-file-directory.markdown b/content/examples/example-snippets/basic-file-directory.markdown index 2e7a4fb75..a1fb95767 100644 --- a/content/examples/example-snippets/basic-file-directory.markdown +++ b/content/examples/example-snippets/basic-file-directory.markdown @@ -4,31 +4,31 @@ title: File and directory examples sorting: 6 --- -* [Create files and directories][File and directory examples#Create files and directories] -* [Copy single files][File and directory examples#Copy single files] -* [Copy directory trees][File and directory examples#Copy directory trees] -* [Disabling and rotating files][File and directory examples#Disabling and rotating files] -* [Add lines to a file][File and directory examples#Add lines to a file] -* [Check file or directory permissions][File and directory examples#Check file or directory permissions] -* [Commenting lines in a file][File and directory examples#Commenting lines in a file] -* [Copy files][File and directory examples#Copy files] -* [Copy and flatten directory][File and directory examples#Copy and flatten directory] -* [Copy then edit a file convergently][File and directory examples#Copy then edit a file convergently] -* [Deleting lines from a file][File and directory examples#Deleting lines from a file] -* [Deleting lines exception][File and directory examples#Deleting lines exception] -* [Delete files recursively][File and directory examples#Delete files recursively] -* [Editing files][File and directory examples#Editing files] -* [Editing tabular files][File and directory examples#Editing tabular files] -* [Inserting lines in a file][File and directory examples#Inserting lines in a file] -* [Back references in filenames][File and directory examples#Back references in filenames] -* [Add variable definitions to a file][File and directory examples#Add variable definitions to a file] -* [Linking files][File and directory examples#Linking files] -* [Listing files-pattern in a directory][File and directory examples#Listing files-pattern in a directory] -* [Locate and transform files][File and directory examples#Locate and transform files] -* [BSD flags][File and directory examples#BSD flags] -* [Search and replace text][File and directory examples#Search and replace text] -* [Selecting a region in a file][File and directory examples#Selecting a region in a file] -* [Warn if matching line in file][File and directory examples#Warn if matching line in file] +- [Create files and directories][File and directory examples#Create files and directories] +- [Copy single files][File and directory examples#Copy single files] +- [Copy directory trees][File and directory examples#Copy directory trees] +- [Disabling and rotating files][File and directory examples#Disabling and rotating files] +- [Add lines to a file][File and directory examples#Add lines to a file] +- [Check file or directory permissions][File and directory examples#Check file or directory permissions] +- [Commenting lines in a file][File and directory examples#Commenting lines in a file] +- [Copy files][File and directory examples#Copy files] +- [Copy and flatten directory][File and directory examples#Copy and flatten directory] +- [Copy then edit a file convergently][File and directory examples#Copy then edit a file convergently] +- [Deleting lines from a file][File and directory examples#Deleting lines from a file] +- [Deleting lines exception][File and directory examples#Deleting lines exception] +- [Delete files recursively][File and directory examples#Delete files recursively] +- [Editing files][File and directory examples#Editing files] +- [Editing tabular files][File and directory examples#Editing tabular files] +- [Inserting lines in a file][File and directory examples#Inserting lines in a file] +- [Back references in filenames][File and directory examples#Back references in filenames] +- [Add variable definitions to a file][File and directory examples#Add variable definitions to a file] +- [Linking files][File and directory examples#Linking files] +- [Listing files-pattern in a directory][File and directory examples#Listing files-pattern in a directory] +- [Locate and transform files][File and directory examples#Locate and transform files] +- [BSD flags][File and directory examples#BSD flags] +- [Search and replace text][File and directory examples#Search and replace text] +- [Selecting a region in a file][File and directory examples#Selecting a region in a file] +- [Warn if matching line in file][File and directory examples#Warn if matching line in file] ## Create files and directories @@ -124,9 +124,9 @@ Here is an example of how to comment out lines matching a number of patterns: Results in: -* lhs1= Mary had a little pig -* lhs2=Whose Fleece was white as snow -* lhs3=And everywhere that Mary went +- lhs1= Mary had a little pig +- lhs2=Whose Fleece was white as snow +- lhs3=And everywhere that Mary went An example of this would be to add variables to /etc/sysctl.conf on Linux: diff --git a/content/examples/example-snippets/cfengine-administration.markdown b/content/examples/example-snippets/cfengine-administration.markdown index 08ef0931a..86d67c780 100644 --- a/content/examples/example-snippets/cfengine-administration.markdown +++ b/content/examples/example-snippets/cfengine-administration.markdown @@ -4,8 +4,8 @@ title: Administration examples sorting: 2 --- -* [Ordering promises][Administration examples#Ordering promises] -* [Aborting execution][Administration examples#Aborting execution] +- [Ordering promises][Administration examples#Ordering promises] +- [Aborting execution][Administration examples#Aborting execution] ## Ordering promises diff --git a/content/examples/example-snippets/commands-scripts-execution.markdown b/content/examples/example-snippets/commands-scripts-execution.markdown index 729eeb909..a959c2800 100644 --- a/content/examples/example-snippets/commands-scripts-execution.markdown +++ b/content/examples/example-snippets/commands-scripts-execution.markdown @@ -4,13 +4,13 @@ title: Commands, scripts, and execution examples sorting: 5 --- -* [Command or script execution][Commands, scripts, and execution examples#Command or script execution] -* [Change directory for command][Commands, scripts, and execution examples#Change directory for command] -* [Commands example][Commands, scripts, and execution examples#Commands example] -* [Execresult example][Commands, scripts, and execution examples#Execresult example] -* [Methods][Commands, scripts, and execution examples#Methods] -* [Method validation][Commands, scripts, and execution examples#Method validation] -* [Trigger classes][Commands, scripts, and execution examples#Trigger classes] +- [Command or script execution][Commands, scripts, and execution examples#Command or script execution] +- [Change directory for command][Commands, scripts, and execution examples#Change directory for command] +- [Commands example][Commands, scripts, and execution examples#Commands example] +- [Execresult example][Commands, scripts, and execution examples#Execresult example] +- [Methods][Commands, scripts, and execution examples#Methods] +- [Method validation][Commands, scripts, and execution examples#Method validation] +- [Trigger classes][Commands, scripts, and execution examples#Trigger classes] ## Command or script execution diff --git a/content/examples/example-snippets/database.markdown b/content/examples/example-snippets/database.markdown index 2b6b3758e..6567e5472 100644 --- a/content/examples/example-snippets/database.markdown +++ b/content/examples/example-snippets/database.markdown @@ -4,7 +4,7 @@ title: Database examples sorting: 8 --- -* [Database creation][Database examples#Database creation] +- [Database creation][Database examples#Database creation] ## Database creation diff --git a/content/examples/example-snippets/file-template.markdown b/content/examples/example-snippets/file-template.markdown index 0b2b23ea2..636df66bb 100644 --- a/content/examples/example-snippets/file-template.markdown +++ b/content/examples/example-snippets/file-template.markdown @@ -4,7 +4,7 @@ title: File template examples sorting: 7 --- -* [Templating][File template examples#Templating] +- [Templating][File template examples#Templating] ## Templating diff --git a/content/examples/example-snippets/general.markdown b/content/examples/example-snippets/general.markdown index ab20f43e8..95a6d6f5f 100644 --- a/content/examples/example-snippets/general.markdown +++ b/content/examples/example-snippets/general.markdown @@ -4,9 +4,9 @@ title: General examples sorting: 1 --- -* [Basic example][General examples#Basic example] -* [Hello world][General examples#Hello world] -* [Array example][General examples#Array example] +- [Basic example][General examples#Basic example] +- [Hello world][General examples#Hello world] +- [Array example][General examples#Array example] ## Basic example diff --git a/content/examples/example-snippets/network.markdown b/content/examples/example-snippets/network.markdown index add098457..967012300 100644 --- a/content/examples/example-snippets/network.markdown +++ b/content/examples/example-snippets/network.markdown @@ -4,15 +4,15 @@ title: Network examples sorting: 9 --- -* [Find MAC address][Network examples#Find MAC address] -* [Client-server example][Network examples#Client-server example] -* [Read from a TCP socket][Network examples#Read from a TCP socket] -* [Set up a PXE boot server][Network examples#Set up a PXE boot server] -* [Resolver management][Network examples#Resolver management] -* [Mount NFS filesystem][Network examples#Mount NFS filesystem] -* [Unmount NFS filesystem][Network examples#Unmount NFS filesystem] -* Find the MAC address -* Mount NFS filesystem +- [Find MAC address][Network examples#Find MAC address] +- [Client-server example][Network examples#Client-server example] +- [Read from a TCP socket][Network examples#Read from a TCP socket] +- [Set up a PXE boot server][Network examples#Set up a PXE boot server] +- [Resolver management][Network examples#Resolver management] +- [Mount NFS filesystem][Network examples#Mount NFS filesystem] +- [Unmount NFS filesystem][Network examples#Unmount NFS filesystem] +- Find the MAC address +- Mount NFS filesystem ## Find MAC address diff --git a/content/examples/example-snippets/promise-patterns/_index.markdown b/content/examples/example-snippets/promise-patterns/_index.markdown index 311a083ef..2b2917f06 100644 --- a/content/examples/example-snippets/promise-patterns/_index.markdown +++ b/content/examples/example-snippets/promise-patterns/_index.markdown @@ -1,26 +1,26 @@ --- layout: default -title: Common promise patterns +title: Common promise patterns sorting: 2 --- This section includes includes common promise patterns. Refer to them as you write policy for your system. -* [Aborting execution][Aborting execution] -* [Change detection][Change detection] -* [Check filesystem space][Check filesystem space] -* [Copy single files][Copy single files] -* [Create files and directories][Create files and directories] -* [Customize message of the day][Customize message of the day] -* [Distribute ssh keys][Distribute ssh keys] -* [Ensure a process is not running][Ensure a process is not running] -* [Ensure a service is enabled and running][Ensure a service is enabled and running] -* [Find the MAC address][Find the MAC address] -* [Install packages][Install packages] -* [Mount NFS filesystem][Mount NFS filesystem] -* [Restart a process][Restart a process] -* [Set up sudo][Set up sudo] -* [Set up time management through NTP][Set up time management through NTP] -* [Set up name resolution with DNS][Set up name resolution with DNS] -* [Updating from a central policy server][Updating from a central policy server] +- [Aborting execution][Aborting execution] +- [Change detection][Change detection] +- [Check filesystem space][Check filesystem space] +- [Copy single files][Copy single files] +- [Create files and directories][Create files and directories] +- [Customize message of the day][Customize message of the day] +- [Distribute ssh keys][Distribute ssh keys] +- [Ensure a process is not running][Ensure a process is not running] +- [Ensure a service is enabled and running][Ensure a service is enabled and running] +- [Find the MAC address][Find the MAC address] +- [Install packages][Install packages] +- [Mount NFS filesystem][Mount NFS filesystem] +- [Restart a process][Restart a process] +- [Set up sudo][Set up sudo] +- [Set up time management through NTP][Set up time management through NTP] +- [Set up name resolution with DNS][Set up name resolution with DNS] +- [Updating from a central policy server][Updating from a central policy server] diff --git a/content/examples/example-snippets/promise-patterns/example_aborting_execution.markdown b/content/examples/example-snippets/promise-patterns/example_aborting_execution.markdown index ea0893f77..0f3b01864 100644 --- a/content/examples/example-snippets/promise-patterns/example_aborting_execution.markdown +++ b/content/examples/example-snippets/promise-patterns/example_aborting_execution.markdown @@ -22,6 +22,7 @@ cf-agent -f unit_abort.cf R: User name mark is valid at 4 letters R: User name john is valid at 4 letters ``` + This is how the policy runs when the userlist contains an invalid entry: ```command @@ -31,13 +32,14 @@ cf-agent -f unit_abort.cf ```output Bundle example aborted on defined class "invalid" ``` + To run this example file as part of your main policy you need to make an additional change: There cannot be two `body agent control` in the main policy. Delete the `body agent control` section from `/var/cfengine/masterfiles/unit_abort.cf`. Copy and paste `abortbundleclasses => { "invalid" };` into -`/var/cfengine/masterfiles/controls/cf_agent.cf`. If you add it to +`/var/cfengine/masterfiles/controls/cf_agent.cf`. If you add it to the end of the file it should look something like this: ```cf3 diff --git a/content/examples/example-snippets/promise-patterns/example_edit_motd.markdown b/content/examples/example-snippets/promise-patterns/example_edit_motd.markdown index 8dd8d801a..afbff101e 100644 --- a/content/examples/example-snippets/promise-patterns/example_edit_motd.markdown +++ b/content/examples/example-snippets/promise-patterns/example_edit_motd.markdown @@ -13,13 +13,13 @@ It is often useful to customize the Message of the Day to inform your users about some specifics of the system they are connecting to. In this example we render a `/etc/motd` using a mustache template and add useful information as: -* The role of the server ( staging / production ) -* The hostname of the server -* The CFEngine version we are running on the host -* The CFEngine role of the server ( client / hub ) -* The administrative contacts details conditionally to the environment -* The primary Ipv4 IP address -* The number of packages updates available for this host +- The role of the server ( staging / production ) +- The hostname of the server +- The CFEngine version we are running on the host +- The CFEngine role of the server ( client / hub ) +- The administrative contacts details conditionally to the environment +- The primary Ipv4 IP address +- The number of packages updates available for this host The bundle is defined like this: diff --git a/content/examples/example-snippets/promise-patterns/example_enable_service.markdown b/content/examples/example-snippets/promise-patterns/example_enable_service.markdown index db7b9084a..c9ecaf3bf 100644 --- a/content/examples/example-snippets/promise-patterns/example_enable_service.markdown +++ b/content/examples/example-snippets/promise-patterns/example_enable_service.markdown @@ -15,13 +15,13 @@ correct return codes for status checks. **See also:** -* [Services promise type reference][services] -* [Services bundles and bodies in the standard library][lib/services.cf] +- [Services promise type reference][services] +- [Services bundles and bodies in the standard library][lib/services.cf] ## Example usage on systemd -We can see that before the policy run `sysstat` is *inactive*, `apache2` is -*active*, `cups` is *active*, `ssh` is *active* and `cron` is *inactive*. +We can see that before the policy run `sysstat` is _inactive_, `apache2` is +_active_, `cups` is _active_, `ssh` is _active_ and `cron` is _inactive_. ```command systemctl is-active sysstat apache2 cups ssh cron @@ -51,7 +51,7 @@ info: Completed execution of '/bin/systemctl --no-ask-password --global --system ``` After the policy run we can see that `systat`, `apache2`, and `cups` are -*inactive*. `ssh` and `cron` are *active* as specified in the policy. +_inactive_. `ssh` and `cron` are _active_ as specified in the policy. ```command systemctl is-active sysstat apache2 cups ssh cron @@ -68,8 +68,8 @@ active ## Example usage with System V We can see that before the policy run `sysstat` is not reporting status -correctly , `httpd` is *running*, `cups` is *running*, `sshd` is *running* and -`crond` is *not running*. +correctly , `httpd` is _running_, `cups` is _running_, `sshd` is _running_ and +`crond` is _not running_. ```command service sysstat status; echo $? @@ -131,7 +131,7 @@ info: Completed execution of '/etc/init.d/cups stop' ``` After the policy run we can see that `systat` is still not reporting status correctly (some services do not respond to standard checks), `apache2`, and `cups` are -*inactive*. `ssh` and `cron` are *active* as specified in the policy. +_inactive_. `ssh` and `cron` are _active_ as specified in the policy. ```command service sysstat status; echo $? diff --git a/content/examples/example-snippets/promise-patterns/example_install_package.markdown b/content/examples/example-snippets/promise-patterns/example_install_package.markdown index ec8721e74..1d222fc39 100644 --- a/content/examples/example-snippets/promise-patterns/example_install_package.markdown +++ b/content/examples/example-snippets/promise-patterns/example_install_package.markdown @@ -38,7 +38,7 @@ using the generic method, you may have to use a method specific to your package manager and get to your elbows in the details. But try `generic` first. You may get lucky. -Mind package names can differ OS to OS. For example, Apache httpd +Mind package names can differ OS to OS. For example, Apache httpd is "httpd" on Red Hat, and "apache2" on Debian. Version comparison can be tricky when involving multipart version @@ -80,6 +80,7 @@ ii ntp 1:4.2.6.p3+dfsg-1ubu amd64 Ne ``` There are examples in `/var/cfengine/share/doc/examples/` of installing packages using specific package managers: + - Red Hat (unit_package_yum.cf) - Debian (unit_package_apt.cf) - MSI for Windows (unit_package_msi_file.cf) diff --git a/content/examples/example-snippets/promise-patterns/example_mount_nfs.markdown b/content/examples/example-snippets/promise-patterns/example_mount_nfs.markdown index 443d904be..703d1fce6 100644 --- a/content/examples/example-snippets/promise-patterns/example_mount_nfs.markdown +++ b/content/examples/example-snippets/promise-patterns/example_mount_nfs.markdown @@ -34,7 +34,7 @@ edit_fstab => "true"; # True/false add or remove entries to the file sy This policy can be found in `/var/cfengine/share/doc/examples/example_mount_nfs.cf` -Here is an example run. At start, the filesystem is not in /etc/fstab and is not mounted: +Here is an example run. At start, the filesystem is not in /etc/fstab and is not mounted: ``` # grep mnt /etc/fstab # filesystem is not in /etc/fstab @@ -68,5 +68,5 @@ fileserver:/home 149912064 94414848 47882240 67% /mnt ``` Note: CFEngine errors out after it mounts the filesystem and updates -/etc/fstab. There is a ticket https://cfengine.com/dev/issues/2937 +/etc/fstab. There is a ticket https://cfengine.com/dev/issues/2937 open on this issue. diff --git a/content/examples/example-snippets/promise-patterns/example_process_restart.markdown b/content/examples/example-snippets/promise-patterns/example_process_restart.markdown index 1665fb3b0..cc6a13775 100644 --- a/content/examples/example-snippets/promise-patterns/example_process_restart.markdown +++ b/content/examples/example-snippets/promise-patterns/example_process_restart.markdown @@ -37,7 +37,7 @@ commands: } ``` -Notes: The `canonify` function translates illegal characters to underscores, e.g. `start_cf-monitord` becomes `start_cf_monitord`. Only alphanumerics and underscores are allowed in CFEngine identifiers (names of variables, classes, bundles, etc.) +Notes: The `canonify` function translates illegal characters to underscores, e.g. `start_cf-monitord` becomes `start_cf_monitord`. Only alphanumerics and underscores are allowed in CFEngine identifiers (names of variables, classes, bundles, etc.) This policy can be found in `/var/cfengine/share/doc/examples/unit_process_restart.cf`. diff --git a/content/examples/example-snippets/promise-patterns/example_updating_from_central_hub.markdown b/content/examples/example-snippets/promise-patterns/example_updating_from_central_hub.markdown index 227638afb..8eda0c448 100644 --- a/content/examples/example-snippets/promise-patterns/example_updating_from_central_hub.markdown +++ b/content/examples/example-snippets/promise-patterns/example_updating_from_central_hub.markdown @@ -9,7 +9,7 @@ This is a conceptual example without any test policy associated with it. The default policy shipped with CFEngine contains a centralized updating of policy that covers more subtleties than this example, and handles fault tolerance. Here is the main -idea behind it. For simplicity, we assume that all hosts are on network 10.20.30.* and that +idea behind it. For simplicity, we assume that all hosts are on network 10.20.30.\* and that the central policy server is 10.20.30.123. ```cf3 @@ -50,7 +50,7 @@ trustkeysfrom => { "127.0.0.1" , "10.20.30.0/24" }; } ``` -Since we assume that all hosts are on network 10.20.30.* they will be granted access. In the default policy this is set to `$(sys.policy_hub)/16`, i.e. all hosts in the same class B network as the hub will gain access. You will need to modify the access control list in `body server control` if you have clients outside of the policy server's class B network. +Since we assume that all hosts are on network 10.20.30.\* they will be granted access. In the default policy this is set to `$(sys.policy_hub)/16`, i.e. all hosts in the same class B network as the hub will gain access. You will need to modify the access control list in `body server control` if you have clients outside of the policy server's class B network. Granting access to files and folders needs to be done using `access` type promises in a `server` bundle, for example, `bundle server my_access_rules()`: diff --git a/content/examples/example-snippets/software-adminstration.markdown b/content/examples/example-snippets/software-adminstration.markdown index 492a9ae84..adf4a2a26 100644 --- a/content/examples/example-snippets/software-adminstration.markdown +++ b/content/examples/example-snippets/software-adminstration.markdown @@ -4,17 +4,17 @@ title: Software administration examples sorting: 4 --- -* [Software and patch installation][Software administration examples#Software and patch installation] -* [Postfix mail configuration][Software administration examples#Postfix mail configuration] -* [Set up a web server][Software administration examples#Set up a web server] -* [Add software packages to the system][Software administration examples#Add software packages to the system] -* [Application baseline][Software administration examples#Application baseline] -* [Service management (windows)][Software administration examples#Service management (windows)] -* [Software distribution][Software administration examples#Software distribution] -* [Web server modules][Software administration examples#Web server modules] -* Ensure a service is enabled and running -* Managing Software -* Install packages +- [Software and patch installation][Software administration examples#Software and patch installation] +- [Postfix mail configuration][Software administration examples#Postfix mail configuration] +- [Set up a web server][Software administration examples#Set up a web server] +- [Add software packages to the system][Software administration examples#Add software packages to the system] +- [Application baseline][Software administration examples#Application baseline] +- [Service management (windows)][Software administration examples#Service management (windows)] +- [Software distribution][Software administration examples#Software distribution] +- [Web server modules][Software administration examples#Web server modules] +- Ensure a service is enabled and running +- Managing Software +- Install packages ## Software and patch installation diff --git a/content/examples/example-snippets/system-administration.markdown b/content/examples/example-snippets/system-administration.markdown index c0eea5585..48802b6b7 100644 --- a/content/examples/example-snippets/system-administration.markdown +++ b/content/examples/example-snippets/system-administration.markdown @@ -20,7 +20,7 @@ This shows the simplest approach in which all hosts are the same. It is too simp ### Updating from a central hub -The configuration bundled with the CFEngine source code contains an example of centralized updating of policy that covers more subtleties than this example, and handles fault tolerance. Here is the main idea behind it. For simplicity, we assume that all hosts are on network 10.20.30.* and that the central policy server/hub is 10.20.30.123. +The configuration bundled with the CFEngine source code contains an example of centralized updating of policy that covers more subtleties than this example, and handles fault tolerance. Here is the main idea behind it. For simplicity, we assume that all hosts are on network 10.20.30.\* and that the central policy server/hub is 10.20.30.123. {{< CFEngine_include_snippet(updating_from_a_central_hub.cf, .* ) >}} diff --git a/content/examples/example-snippets/system-information.markdown b/content/examples/example-snippets/system-information.markdown index 544acddd2..ca565709d 100644 --- a/content/examples/example-snippets/system-information.markdown +++ b/content/examples/example-snippets/system-information.markdown @@ -4,13 +4,13 @@ title: System information examples sorting: 11 --- -* [Change detection][System information examples#Change detection] -* [Hashing for change detection (tripwire)][System information examples#Hashing for change detection (tripwire)] -* [Check filesystem space][System information examples#Check filesystem space] -* [Class match example][System information examples#Class match example] -* [Global classes][System information examples#Global classes] -* [Logging][System information examples#Logging] -* Check filesystem space +- [Change detection][System information examples#Change detection] +- [Hashing for change detection (tripwire)][System information examples#Hashing for change detection (tripwire)] +- [Check filesystem space][System information examples#Check filesystem space] +- [Class match example][System information examples#Class match example] +- [Global classes][System information examples#Global classes] +- [Logging][System information examples#Logging] +- Check filesystem space ## Change detection diff --git a/content/examples/example-snippets/system-security.markdown b/content/examples/example-snippets/system-security.markdown index 1b2d01c77..6d8f65f04 100644 --- a/content/examples/example-snippets/system-security.markdown +++ b/content/examples/example-snippets/system-security.markdown @@ -4,9 +4,9 @@ title: System security examples sorting: 10 --- -* [Distribute root passwords][System security examples#Distribute root passwords] -* [Distribute ssh keys][System security examples#Distribute ssh keys] -* Distribute ssh keys +- [Distribute root passwords][System security examples#Distribute root passwords] +- [Distribute ssh keys][System security examples#Distribute ssh keys] +- Distribute ssh keys ## Distribute root passwords diff --git a/content/examples/example-snippets/timing-counting-measuring.markdown b/content/examples/example-snippets/timing-counting-measuring.markdown index 5b4504de0..24a5fc900 100644 --- a/content/examples/example-snippets/timing-counting-measuring.markdown +++ b/content/examples/example-snippets/timing-counting-measuring.markdown @@ -4,7 +4,7 @@ title: Measuring examples sorting: 3 --- -* [Measurements][Measuring examples#Measurements] +- [Measurements][Measuring examples#Measurements] ## Measurements diff --git a/content/examples/example-snippets/user-management.markdown b/content/examples/example-snippets/user-management.markdown index 9408e701b..15635becc 100644 --- a/content/examples/example-snippets/user-management.markdown +++ b/content/examples/example-snippets/user-management.markdown @@ -8,7 +8,7 @@ sorting: 15 There are many approaches to managing users. You can edit system files like `/etc/passwd` directly, you can use commands on some systems like -`useradd`. However the easiest, and preferred way is to use +`useradd`. However the easiest, and preferred way is to use CFEngine's native `users` type promise. ### Ensuring a local user has a specific password @@ -26,6 +26,7 @@ root@debian-jessie:/core/examples# cf-agent -KIf ./local_user_password.cf root@debian-jessie:/core/examples# grep root /etc/shadow root:$6$1nRTeNoE$DpBSe.eDsuZaME0EydXBEf.DAwuzpSoIJhkhiIAPgRqVKlmI55EONfvjZorkxNQvK2VFfMm9txx93r2bma/4h/:16791:0:99999:7::: ``` + ### Ensuring local users are present This example shows ensuring that the local users `jack` and `jill` are diff --git a/content/examples/example-snippets/windows-registry.markdown b/content/examples/example-snippets/windows-registry.markdown index e692b8ad7..8cdab3fd5 100644 --- a/content/examples/example-snippets/windows-registry.markdown +++ b/content/examples/example-snippets/windows-registry.markdown @@ -4,9 +4,9 @@ title: Windows registry examples sorting: 14 --- -* [Windows registry][Windows registry examples#Windows registry] -* [unit_registry_cache.cf][Windows registry examples#unit_registry_cache.cf] -* [unit_registry.cf][Windows registry examples#unit_registry.cf] +- [Windows registry][Windows registry examples#Windows registry] +- [unit_registry_cache.cf][Windows registry examples#unit_registry_cache.cf] +- [unit_registry.cf][Windows registry examples#unit_registry.cf] ## Windows registry diff --git a/content/examples/tutorials/custom_inventory.markdown b/content/examples/tutorials/custom_inventory.markdown index 20e51d523..9de937ee9 100644 --- a/content/examples/tutorials/custom_inventory.markdown +++ b/content/examples/tutorials/custom_inventory.markdown @@ -13,11 +13,11 @@ For a more detailed overview on how the inventory system works please reference This tutorial provides instructions for the following: -* [Choose an attribute][Custom inventory#Choose an attribute to inventory] +- [Choose an attribute][Custom inventory#Choose an attribute to inventory] -* [Create and deploy inventory policy][Custom inventory#Create and deploy inventory policy] +- [Create and deploy inventory policy][Custom inventory#Create and deploy inventory policy] -* [Run Reports][Custom inventory#Reporting] +- [Run Reports][Custom inventory#Reporting] **Note:** This tutorial uses the [CFEngine Enterprise Vagrant Environment][Using Vagrant] and files located in the vagrant project directory are automatically available to all hosts. @@ -92,7 +92,7 @@ Create `/var/cfengine/masterfiles/def.json` and populate it with the following c } ``` -Any time you modify something, it is *always* a good idea to validate the syntax. You can run `cf-promises` to check policy syntax. +Any time you modify something, it is _always_ a good idea to validate the syntax. You can run `cf-promises` to check policy syntax. **Policy Validation:** diff --git a/content/examples/tutorials/distribute-files-from-a-central-location.markdown b/content/examples/tutorials/distribute-files-from-a-central-location.markdown index 6202b9f73..3c2552854 100644 --- a/content/examples/tutorials/distribute-files-from-a-central-location.markdown +++ b/content/examples/tutorials/distribute-files-from-a-central-location.markdown @@ -40,7 +40,7 @@ especially useful in the case of file copies because the same variable definition can be used both by the policy server when granting access and by the agent host when performing the copy. -The policy framework includes a common bundle called ```def```. In this example, we +The policy framework includes a common bundle called `def`. In this example, we will add two variables--`dir_patch_store` and `dir_patch_deploy`--to this existing bundle. These variables provide path definitions for storing and deploying patches. @@ -61,7 +61,7 @@ Add the following variable information to the `masterfiles/def.cf` file: ``` These common variables can be referenced from the rest of the policy by using their fully - [qualified names][Variables#Scalar referencing and expansion], +[qualified names][Variables#Scalar referencing and expansion], `$(def.dir_patch_store)` and `$(def.dir_patch_deploy)` ### Grant file access @@ -107,6 +107,7 @@ bundle agent sync_from_policyserver(source_path, dest_path) comment => "Ensure files from $(sys.policy_hub):$(source_path) exist in $(dest_path)"; } ``` + This reusable policy will be used to synchronize a directory on the policy server to a directory on the agent host. @@ -199,14 +200,14 @@ in the right-hand panel. Click **Add new tracker**. ![Mission Portal Host Event](hosts-add-new-tracker.png) -Name it *Patch Failure*. Set the -**Report Type** to *Promise not Kept*. Under **Watch**, enter **.patch**. Set the **Start Time** to **Now** +Name it _Patch Failure_. Set the +**Report Type** to _Promise not Kept_. Under **Watch**, enter **.patch**. Set the **Start Time** to **Now** and then click **Done** to close the Start Time window. Click **Start** to save the new tracker. -This tracker watches for any promise handle that includes the string patch where a promise is not kept. +This tracker watches for any promise handle that includes the string patch where a promise is not kept. ![Add New Tracker](add-new-tracker.png) -Add another tracker called *Patch Repaired*. Set the **Report Type** to *Promise Repaired*. +Add another tracker called _Patch Repaired_. Set the **Report Type** to _Promise Repaired_. Enter the same values as above for **Watch** and **Start Time**. Click **Start** to save the new tracker. This tracker allows you to see how the policy reacts as it is activated on your infrastructure. diff --git a/content/examples/tutorials/file_comparison.markdown b/content/examples/tutorials/file_comparison.markdown index d322d754d..be8ad2cee 100644 --- a/content/examples/tutorials/file_comparison.markdown +++ b/content/examples/tutorials/file_comparison.markdown @@ -6,6 +6,7 @@ sorting: 100 1. Add the [policy contents][File comparison#Full policy] (also can be downloaded from file_compare_test.cf) to a new file, such as /var/cfengine/masterfiles/file_test.cf. 2. Run the following commands as root on the command line: + ```console export AOUT_BIN="a.out" export GCC_BIN="/usr/bin/gcc" @@ -130,7 +131,7 @@ bundle agent create_aout_source_file ## create_aout -This bundle creates a binary application from the source in create_aout_source_file that uses the stat library to compare two files, determine if the modified times are different, nd whether the second file is newer than the first. +This bundle creates a binary application from the source in create_aout_source_file that uses the stat library to compare two files, determine if the modified times are different, nd whether the second file is newer than the first. The difference between this application and using CFEngine's built in support for getting file stats is that normally the accuracy is only to the second of the modified file time but in order to better compare two files requires parts of a second as well. The stat library provides the extra support for retrieving the additional information required. diff --git a/content/examples/tutorials/files-tutorial.markdown b/content/examples/tutorials/files-tutorial.markdown index 38a8a3646..4ee717128 100644 --- a/content/examples/tutorials/files-tutorial.markdown +++ b/content/examples/tutorials/files-tutorial.markdown @@ -6,9 +6,9 @@ sorting: 10 ## Prerequisites -* Read the tutorial [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] -* Ensure you have read and understand the section on [how to make an example stand alone][Examples and tutorials#Make the example stand alone] -* Ensure you have read the note at the end of that section regarding modification of the body common control to the following: +- Read the tutorial [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] +- Ensure you have read and understand the section on [how to make an example stand alone][Examples and tutorials#Make the example stand alone] +- Ensure you have read the note at the end of that section regarding modification of the body common control to the following: ```cf3 body common control @@ -50,31 +50,31 @@ Note: The following workflow assumes the directory /home/user already exists. If ls /home/user/test_plain.txt ``` -5. Run the following command to instruct CFEngine to see if the file exists (the expected result is that no report will be generated (because the file does not exist): +4. Run the following command to instruct CFEngine to see if the file exists (the expected result is that no report will be generated (because the file does not exist): ```command /var/cfengine/bin/cf-agent --no-lock --file /var/cfengine/masterfiles/file_test.cf --bundlesequence list_file ``` -6. Create a file for testing the example, using the following command: +5. Create a file for testing the example, using the following command: ```command touch /home/user/test_plain.txt ``` -7. Run the following command to instruct CFEngine to search for the file (the expected result is that a report will be generated, because the file exists): +6. Run the following command to instruct CFEngine to search for the file (the expected result is that a report will be generated, because the file exists): ```command /var/cfengine/bin/cf-agent --no-lock --file /var/cfengine/masterfiles/file_test.cf --bundlesequence list_file ``` -8. Double check the file exists, using the following command (the expected result is that there will be a file listed at the location /home/user/test_plain.txt): +7. Double check the file exists, using the following command (the expected result is that there will be a file listed at the location /home/user/test_plain.txt): ```command ls /home/user/test_plain.txt ``` -9. Run the following command to remove the file: +8. Run the following command to remove the file: ```command rm /home/user/test_plain.txt @@ -113,6 +113,7 @@ body perms system mode => "0640"; } ``` + ```console ls /home/user/test_plain.txt /var/cfengine/bin/cf-agent --no-lock --file ./file_test.cf --bundlesequence list_file,testbundle,list_file_2 @@ -169,6 +170,7 @@ body perms system mode => "0640"; } ``` + ```bash rm /home/user/test_plain.txt ls /home/user/test_plain.txt @@ -178,6 +180,7 @@ ls /home/user/test_plain.txt ls /home/user/test_plain.txt rm /home/user/test_plain.txt ``` + (last command will throw an error because the file doesn't exist!) ## Modify a File diff --git a/content/examples/tutorials/high-availability/_index.markdown b/content/examples/tutorials/high-availability/_index.markdown index 100da7a34..028823f41 100644 --- a/content/examples/tutorials/high-availability/_index.markdown +++ b/content/examples/tutorials/high-availability/_index.markdown @@ -8,7 +8,7 @@ title: High availability Although CFEngine is a distributed system, with decisions made by autonomous agents running on each node, the hub can be viewed as a single point of failure. In order to be able to play both roles that hub is responsible for - policy serving and report collection - High availability feature was -introduced in 3.6.2. Essentially it is based on well known and broadly used cluster resource +introduced in 3.6.2. Essentially it is based on well known and broadly used cluster resource management tools - [corosync](https://corosync.github.io/corosync/) and [pacemaker](https://clusterlabs.org/pacemaker/) as well as PostgreSQL streaming replication feature. @@ -80,7 +80,7 @@ knowledge and overview of the whole setup. There are also new Mission Portal inventory variables indicating the IP address of the active hub instance and status of the High availability installation on each of the hubs. Looking at inventory reports is especially helpful to diagnose any problems when High availability is reported as -*degraded*. +_degraded_. HAInventory diff --git a/content/examples/tutorials/high-availability/installation-guide.markdown b/content/examples/tutorials/high-availability/installation-guide.markdown index b37d2aee1..04d62c42b 100644 --- a/content/examples/tutorials/high-availability/installation-guide.markdown +++ b/content/examples/tutorials/high-availability/installation-guide.markdown @@ -22,29 +22,29 @@ all your CFEngine clients in case of failover. ### Hardware configuration and OS pre-configuration steps -* CFEngine 3.15.3 (or later) hub package for RHEL7 or CentOS7. -* We recommend selecting dedicated interface used for PostgreSQL replication and optionally one for heartbeat. -* We recommend having one shared IP address assigned for interface where MP is accessible +- CFEngine 3.15.3 (or later) hub package for RHEL7 or CentOS7. +- We recommend selecting dedicated interface used for PostgreSQL replication and optionally one for heartbeat. +- We recommend having one shared IP address assigned for interface where MP is accessible (optionally) and one where PostgreSQL replication is configured (mandatory). -* Both active and passive hub machines must be configured so that host names are different. -* Basic hostname resolution works (hub names can be placed in */etc/hosts* or DNS configured). +- Both active and passive hub machines must be configured so that host names are different. +- Basic hostname resolution works (hub names can be placed in _/etc/hosts_ or DNS configured). ### Example configuration used in this tutorial In this tutorial we use the following network configuration: -* Two nodes, one acting as active (node1) and one acting as passive (node2). -* Optionally a third node (node3) used as a database backup for offsite replication. -* Each node having three NICs so that eth0 is used for the heartbeat, eth1 is used for PostgreSQL +- Two nodes, one acting as active (node1) and one acting as passive (node2). +- Optionally a third node (node3) used as a database backup for offsite replication. +- Each node having three NICs so that eth0 is used for the heartbeat, eth1 is used for PostgreSQL replication and eth2 is used for MP and bootstrapping clients. -* IP addresses configured as follows: +- IP addresses configured as follows: -| Node | eth0 | eth1 | eth2 | -|-----------------|:-------------|:---------------|:----------------| -|node1 | 192.168.0.10 | 192.168.10.10 | 192.168.100.10 | -|node2 | 192.168.0.11 | 192.168.10.11 | 192.168.100.11 | -|node3 (optional) | --- | 192.168.10.12 | 192.168.100.12 | -|cluster shared | --- | --- | 192.168.100.100 | +| Node | eth0 | eth1 | eth2 | +| ---------------- | :----------- | :------------ | :-------------- | +| node1 | 192.168.0.10 | 192.168.10.10 | 192.168.100.10 | +| node2 | 192.168.0.11 | 192.168.10.11 | 192.168.100.11 | +| node3 (optional) | --- | 192.168.10.12 | 192.168.100.12 | +| cluster shared | --- | --- | 192.168.100.100 | Detailed network configuration is shown on the picture below: @@ -52,25 +52,25 @@ Detailed network configuration is shown on the picture below: ## Install cluster management tools - **On both nodes:** +**On both nodes:** - ```command - yum -y install pcs pacemaker cman fence-agents - ``` +```command +yum -y install pcs pacemaker cman fence-agents +``` In order to operate cluster, proper fencing must be configured but description how to fence cluster and what mechanism use is out of the scope of this document. For reference please use the [Red Hat HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/configuring_the_red_hat_high_availability_add-on_with_pacemaker/ch-fencing-haar). **IMPORTANT:** please carefully follow the indicators describing if the given step should be - performed on the active (node1), the passive (node2) or both nodes. +performed on the active (node1), the passive (node2) or both nodes. 1. Make sure that the hostnames of all nodes nodes are node1 and node2 respectively. Running - the command ```uname -n | tr '[A-Z]' '[a-z]'``` should return the correct node name. Make sure that + the command `uname -n | tr '[A-Z]' '[a-z]'` should return the correct node name. Make sure that the DNS or entries in /etc/hosts are updated so that hosts can be accessed using their host names. -2. In order to use *pcs* to manage the cluster, create the *hacluster* user designated to manage the - cluster with ```passwd hacluster``` **on both nodes**. +2. In order to use _pcs_ to manage the cluster, create the _hacluster_ user designated to manage the + cluster with `passwd hacluster` **on both nodes**. 3. Make sure that pcsd demon is started and configure both nodes so that it will be enabled to boot on startup **on both nodes**. @@ -99,7 +99,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri pcs cluster setup --name cfcluster node1 node2 ``` - This will create the cluster ```cfcluster``` consisting of node1 and node2. + This will create the cluster `cfcluster` consisting of node1 and node2. 6. Give the cluster time to settle (cca 1 minute) and then start the cluster by running the following command **on the node1**: @@ -110,7 +110,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri This will start the cluster and all the necessary deamons on both nodes. -7. At this point the cluster should be up and running. Running ```pcs status``` should print +7. At this point the cluster should be up and running. Running `pcs status` should print something similar to the output below. ```output @@ -189,14 +189,14 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ``` 3. Configure PostgreSQL **on node1**: - 1. Create two special directories owned by the *cfpostgres* user: + 1. Create two special directories owned by the _cfpostgres_ user: ``` mkdir -p /var/cfengine/state/pg/{data/pg_arch,tmp} chown -R cfpostgres:cfpostgres /var/cfengine/state/pg/{data/pg_arch,tmp} ``` - 2. Modify the */var/cfengine/state/pg/data/postgresql.conf* configuration file to set the + 2. Modify the _/var/cfengine/state/pg/data/postgresql.conf_ configuration file to set the following options accordingly (**uncomment the lines if they are commented out**): ``` @@ -210,7 +210,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri archive_command = 'cp %p /var/cfengine/state/pg/data/pg_arch/%f' ``` - 3. Modify the *pg_hba.conf* configuration file to enable access to PostgreSQL for replication + 3. Modify the _pg_hba.conf_ configuration file to enable access to PostgreSQL for replication between the nodes (note that the second pair of IP addresses, not the heartbeat pair, is used here): @@ -220,10 +220,10 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ``` **IMPORTANT:** The above configuration allows accessing PostgreSQL without any authentication - from both cluster nodes. For security reasons we strongly advise to create a - replication user in PostgreSQL and protect access using a password or - certificate. Furthermore, we advise using ssl-secured replication instead of - the unencrypted method described here if the hubs are in an untrusted network. + from both cluster nodes. For security reasons we strongly advise to create a + replication user in PostgreSQL and protect access using a password or + certificate. Furthermore, we advise using ssl-secured replication instead of + the unencrypted method described here if the hubs are in an untrusted network. 4. Do an initial sync of PostgreSQL: 1. Start PostgreSQL **on node1**: @@ -239,7 +239,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_basebackup -h 192.168.10.10 -U cfpostgres -D /var/cfengine/state/pg/data -X stream -P"; popd ``` - 3. **On node2**, create the *standby.conf* file and configure PostgreSQL to run as a hot-standby replica: + 3. **On node2**, create the _standby.conf_ file and configure PostgreSQL to run as a hot-standby replica: ``` cat < /var/cfengine/state/pg/data/standby.conf @@ -254,9 +254,9 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 5. Start PostgreSQL on the **node2** by running the following command: - ```command - pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_ctl -D /var/cfengine/state/pg/data -l /var/log/postgresql.log start"; popd - ``` + ```command + pushd /tmp; su cfpostgres -c "/var/cfengine/bin/pg_ctl -D /var/cfengine/state/pg/data -l /var/log/postgresql.log start"; popd + ``` 6. Check that PostgreSQL replication is setup and working properly: 1. The **node2** should report it is in the recovery mode: @@ -431,8 +431,8 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ``` **IMPORTANT:** Please make sure that there's one Master node and one Slave node and that the - *cfpgsql-status* for the active node is reported as *PRI* and passive as - *HS:async* or *HS:alone*. + _cfpgsql-status_ for the active node is reported as _PRI_ and passive as + _HS:async_ or _HS:alone_. ### CFEngine configuration @@ -446,8 +446,8 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri EOF ``` -2. Mask the *cf-postgres.service* and make sure it is not required by the - *cf-hub.service* **on both nodes** (PostgreSQL is managed by the cluster +2. Mask the _cf-postgres.service_ and make sure it is not required by the + _cf-hub.service_ **on both nodes** (PostgreSQL is managed by the cluster resource, not by the service). ``` @@ -507,7 +507,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri **IMPORTANT:** Copy over only the hashes, without the `SHA=` prefix. -6. **On both nodes,** add the following class definition to the */var/cfengine/masterfiles/def.json* +6. **On both nodes,** add the following class definition to the _/var/cfengine/masterfiles/def.json_ file to enable HA: ```json {file="def.json"} @@ -517,7 +517,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ``` 7. **On both nodes,** run `cf-agent -Kf update.cf` to make sure that the new policy is copied from - *masterfiles* to *inputs*. + _masterfiles_ to _inputs_. 8. Start CFEngine **on both nodes**. @@ -569,6 +569,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ```command cat /var/cfengine/masterfiles/cfe_internal/enterprise/ha/ha_info.json ``` + ```output { "192.168.100.10": @@ -591,7 +592,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri } ``` - Please note that ```is_in_cluster``` parameter is optional for the 2 nodes in the HA cluster and + Please note that `is_in_cluster` parameter is optional for the 2 nodes in the HA cluster and by default is set to true. For the 3-node setup, the node3, which is not part of the cluster, **MUST** be marked with `"is_in_cluster" : false` configuration parameter. @@ -605,21 +606,22 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri 2. Verify that PostgreSQL is running on 3rd node and data replication from active node is not in progress. If database is actively replicating data with active cluster node make sure that this process will be finished and no new data will be stored in active database instance. -3. After verifying that replication is finished and data is synchronized between active database node and replica node (or once node1 and node2 are both down) promote PostgreSQL to exit recovery and begin read-write operations ```cd /tmp && su cfpostgres -c "/var/cfengine/bin/pg_ctl -c -w -D /var/cfengine/state/pg/data -l /var/log/postgresql.log promote"```. +3. After verifying that replication is finished and data is synchronized between active database node and replica node (or once node1 and node2 are both down) promote PostgreSQL to exit recovery and begin read-write operations `cd /tmp && su cfpostgres -c "/var/cfengine/bin/pg_ctl -c -w -D /var/cfengine/state/pg/data -l /var/log/postgresql.log promote"`. -4. In order to make failover process as easy as possible there is ```"failover_to_replication_node_enabled"``` class defined both in */var/cfengine/masterfiles/controls/VERSION/def.cf* and */var/cfengine/masterfiles/controls/VERSION/update_def.cf*. In order to stat collecting reports and serving policy from 3rd node uncomment the line defining mentioned class. +4. In order to make failover process as easy as possible there is `"failover_to_replication_node_enabled"` class defined both in _/var/cfengine/masterfiles/controls/VERSION/def.cf_ and _/var/cfengine/masterfiles/controls/VERSION/update_def.cf_. In order to stat collecting reports and serving policy from 3rd node uncomment the line defining mentioned class. **IMPORTANT:** Please note that as long as any of the active or passive cluster nodes is accessible by client to be contacted, failover to 3rd node is not possible. If the active or passive node is running and failover to 3rd node is required make sure to disable network interfaces where clients are bootstrapped to so that clients won't be able to access any other node than disaster-recovery. ### Troubleshooting -1. If either the IPaddr2 or pgslq resource is not running, try to enable it first with ```pcs cluster enable --all```. If this is not strting the resources, you can try to run them in debug mode with this command ```pcs resource debug-start ```. The latter command should print diagnostics messages on why resources are not started. +1. If either the IPaddr2 or pgslq resource is not running, try to enable it first with `pcs cluster enable --all`. If this is not strting the resources, you can try to run them in debug mode with this command `pcs resource debug-start `. The latter command should print diagnostics messages on why resources are not started. -2. If ```crm_mon -Afr1``` is printing errors similar to the below +2. If `crm_mon -Afr1` is printing errors similar to the below ```command pcs status ``` + ```output Cluster name: cfcluster Last updated: Tue Jul 7 11:27:23 2015 @@ -644,17 +646,20 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri cfpgsql_start_0 on node1 'unknown error' (1): call=13, status=complete, last-rc-change='Tue Jul 7 11:25:32 2015', queued=1ms, exec=137ms ``` - You can try to clear the errors by running ```pcs resource cleanup ```. This should clean errors for the appropriate resource and make the cluster restart it. + You can try to clear the errors by running `pcs resource cleanup `. This should clean errors for the appropriate resource and make the cluster restart it. ```command pcs resource cleanup cfpgsql ``` + ```output Resource: cfpgsql successfully cleaned up ``` + ```command pcs status ``` + ```output Cluster name: cfcluster Last updated: Tue Jul 7 11:29:36 2015 @@ -682,6 +687,7 @@ HA fencing guide](https://access.redhat.com/documentation/en-us/red_hat_enterpri ```command pcs cluster start ``` + ```output Starting Cluster... ``` diff --git a/content/examples/tutorials/installing-cfengine-enterprise-agent.markdown b/content/examples/tutorials/installing-cfengine-enterprise-agent.markdown index 5e2299b16..0c99f6846 100644 --- a/content/examples/tutorials/installing-cfengine-enterprise-agent.markdown +++ b/content/examples/tutorials/installing-cfengine-enterprise-agent.markdown @@ -14,30 +14,31 @@ This is the full version of CFEngine Enterprise host, but the number of hosts is CFEngine Hosts (clients) -* 32/64-bit machines with a recent version of Linux -* 20 mb of memory -* 20mb of disk space -* Port 5308 needs to be open +- 32/64-bit machines with a recent version of Linux +- 20 mb of memory +- 20mb of disk space +- Port 5308 needs to be open The installation script below has been tested on Red Hat, CentOS, SUSE, Debian and Ubuntu. 1. Download and Install CFEngine Host -Run the following command to download and automatically install CFEngine on a 32-bit or 64-bit Linux machine (the script will detect correct flavor and architecture). + Run the following command to download and automatically install CFEngine on a 32-bit or 64-bit Linux machine (the script will detect correct flavor and architecture). ```command wget https://s3.amazonaws.com/cfengine.packages/quick-install-cfengine-enterprise.sh && sudo bash ./quick-install-cfengine-enterprise.sh agent ``` 2. Bootstrap the Host -Once installed, the host needs to bootstrap to your CFEngine policy server. + Once installed, the host needs to bootstrap to your CFEngine policy server. ```command sudo /var/cfengine/bin/cf-agent --bootstrap ``` + If you encounter any issue, please make sure the host is on the same domain/subnet as CFEngine policy server will only allow connection from these trusted sources as default configuration. 3. Congratulation you are done! -The CFEngine host is installed and ready. That was easy, wasn't it? + The CFEngine host is installed and ready. That was easy, wasn't it? If you would like to see what version of CFEngine you are running, type: diff --git a/content/examples/tutorials/integrating-alerts-with-pager-duty.markdown b/content/examples/tutorials/integrating-alerts-with-pager-duty.markdown index 600f0b6e5..0984b0e95 100644 --- a/content/examples/tutorials/integrating-alerts-with-pager-duty.markdown +++ b/content/examples/tutorials/integrating-alerts-with-pager-duty.markdown @@ -10,8 +10,8 @@ We will create a policy that ensures file integrity, and have CFEngine notify Pa **System requirements:** -* CFEngine Mission Portal -* Active PagerDuty Account +- CFEngine Mission Portal +- Active PagerDuty Account @@ -52,11 +52,11 @@ Normally, to ensure your policy file is put into action, you would need to follo 1. Move the policy file to your masterfiles directory (`/var/cfengine/masterfiles`): - Normally, to ensure your policy file is put into action, you would need to follow these three steps: + Normally, to ensure your policy file is put into action, you would need to follow these three steps: - ```command - mv /tmp/file_example.cf /var/cfengine/masterfiles/ - ``` + ```command + mv /tmp/file_example.cf /var/cfengine/masterfiles/ + ``` 2. Modify `promises.cf` to include your policy @@ -66,13 +66,13 @@ Normally, to ensure your policy file is put into action, you would need to follo vi /var/cfengine/masterfiles/promises.cf ``` - a) Under the body common control, add `file_integrity` to your *bundlesequence* + a) Under the body common control, add `file_integrity` to your _bundlesequence_ - ![integrating-alerts-with-pagerduty_bundlesequence-800x357.png](integrating-alerts-with-pagerduty_bundlesequence-800x357.png) + ![integrating-alerts-with-pagerduty_bundlesequence-800x357.png](integrating-alerts-with-pagerduty_bundlesequence-800x357.png) b) Under `body common control`, add `file_example.cf` to your inputs section. - ![integrating-alerts-with-pagerduty_inputs-800x179.png](integrating-alerts-with-pagerduty_inputs-800x179.png) + ![integrating-alerts-with-pagerduty_inputs-800x179.png](integrating-alerts-with-pagerduty_inputs-800x179.png) Now, any change you manually make to the `/tmp/file_integrity` file will be picked up by CFEngine! @@ -104,7 +104,7 @@ Normally, to ensure your policy file is put into action, you would need to follo ![integrating-alerts-with-pagerduty_type_policy.png](integrating-alerts-with-pagerduty_type_policy.png) -4. Select `Bundle`, type in the bundle name which is *file_integrity*, and finally select `Repaired` as the promise status. This means that whenever CFEngine needs to repair the bundle, it will create an alert notification. +4. Select `Bundle`, type in the bundle name which is _file_integrity_, and finally select `Repaired` as the promise status. This means that whenever CFEngine needs to repair the bundle, it will create an alert notification. ![integrating-alerts-with-pagerduty_new_alert_bundle_repair.png](integrating-alerts-with-pagerduty_new_alert_bundle_repair.png) diff --git a/content/examples/tutorials/integrating-alerts-with-ticketing-systems.markdown b/content/examples/tutorials/integrating-alerts-with-ticketing-systems.markdown index 5b0eff5c3..920d673c2 100644 --- a/content/examples/tutorials/integrating-alerts-with-ticketing-systems.markdown +++ b/content/examples/tutorials/integrating-alerts-with-ticketing-systems.markdown @@ -20,11 +20,11 @@ Note however that it is possible to expand on this by adjusting the Custom actio 1. Log in to the console of your CFEngine hub, and make sure you have python and the jira python package installed (normally by running `pip install jira`). -2. On your workstation, unpack [cfengine\_custom\_action\_jira.py](integrating-alerts-with-ticketing-systems_cfengine_custom_action_jira.py.zip) to a working directory. +2. On your workstation, unpack [cfengine_custom_action_jira.py](integrating-alerts-with-ticketing-systems_cfengine_custom_action_jira.py.zip) to a working directory. 3. Inside the script, fill in `MYJIRASERVER`, `MYUSERNAME` and `MYPASSWORD` with your information. -4. Test the script by unpacking [alert\_parameters\_test](integrating-alerts-with-ticketing-systems_alert_parameters_test.zip) into the same directory and running `./cfengine_custom_action_jira.py alert_parameters`. +4. Test the script by unpacking [alert_parameters_test](integrating-alerts-with-ticketing-systems_alert_parameters_test.zip) into the same directory and running `./cfengine_custom_action_jira.py alert_parameters`. 5. Verify the previous step created a ticket in JIRA. If not, recheck the information to typed in, connectivity and any output generated when running the script. @@ -34,9 +34,9 @@ Note however that it is possible to expand on this by adjusting the Custom actio 2. Click on the button to Add a script, upload the script and fill in the information as shown in the screenshot. - ![Upload custom action script](integrating-alerts-with-ticketing-systems_custom-action-script-upload-jira.png) + ![Upload custom action script](integrating-alerts-with-ticketing-systems_custom-action-script-upload-jira.png) -3. Click save to allow the script to be used when creating alerts. +3. Click save to allow the script to be used when creating alerts. ## Create a new alert and associate the custom action script @@ -44,7 +44,7 @@ Note however that it is possible to expand on this by adjusting the Custom actio 2. Click on the existing Policy compliance widget, followed by Add alert. - ![Add alert to Policy Compliance widget](integrating-alerts-with-ticketing-systems_policy-compliance-add-alert.png) + ![Add alert to Policy Compliance widget](integrating-alerts-with-ticketing-systems_policy-compliance-add-alert.png) 3. Name the alert "`Web service`" and set `Severity-level` at "`high`". @@ -56,16 +56,16 @@ Note however that it is possible to expand on this by adjusting the Custom actio 7. Type Promise Status to "`Not kept`". - ![Set Type Promise Status to Not kept](integrating-alerts-with-ticketing-systems_web-service-condition.png) + ![Set Type Promise Status to Not kept](integrating-alerts-with-ticketing-systems_web-service-condition.png) 8. Associate the Custom action script we uploaded with the alert. - ![Associate custom action script with alert](integrating-alerts-with-ticketing-systems_custom-action-alert-association-jira.png) + ![Associate custom action script with alert](integrating-alerts-with-ticketing-systems_custom-action-alert-association-jira.png) ## Conclusions In this tutorial, we have shown how easy it is to integrate with a ticketing system, with JIRA as an example, using CFEngine Custom actions scripts. -Using this Custom action, you can choose to open JIRA tickets when some or all of your alerts are triggered. But this is just the beginning; using Custom actions, you can integrate with virtually *any* external system for notifying about- or handling triggered alerts. +Using this Custom action, you can choose to open JIRA tickets when some or all of your alerts are triggered. But this is just the beginning; using Custom actions, you can integrate with virtually _any_ external system for notifying about- or handling triggered alerts. Read more in the [Custom action documentation][Custom actions for alerts]. diff --git a/content/examples/tutorials/integrating-with-sumo-logic.markdown b/content/examples/tutorials/integrating-with-sumo-logic.markdown index 38cec2502..b42275007 100644 --- a/content/examples/tutorials/integrating-with-sumo-logic.markdown +++ b/content/examples/tutorials/integrating-with-sumo-logic.markdown @@ -3,12 +3,13 @@ layout: default title: Integrating with Sumo Logic sorting: 15 --- + In this How To we will show a simple integrate with [Sumo Logic](http://www.sumologic.com). Whenever there is a CFEngine policy update, that event will be exported to Sumo Logic. These events can become valuable traces when using Sumo Logic to analyze and detect unintendent system behavior. **Requirements:** -- CFEngine Community/Enterprise -- Sumo Logic account (secret URL) +- CFEngine Community/Enterprise +- Sumo Logic account (secret URL) @@ -115,7 +116,7 @@ body common control ... ``` -Under body common control, add /sumologic\_policy\_update.cf/ to your inputs section. +Under body common control, add /sumologic_policy_update.cf/ to your inputs section. ```cf3 inputs => { @@ -130,7 +131,7 @@ That's all. To test it, we need to make a change to any CFEngine policy, and then go to Sumo Logic to see if there is a new timestamp reported. -* Make a change to any policy file, for examle `promises.cf`: +- Make a change to any policy file, for examle `promises.cf`: ```command vi /var/cfengine/masterfiles/promises.cf @@ -138,13 +139,13 @@ vi /var/cfengine/masterfiles/promises.cf Add a comment and close the file. -* Check if timestamp has been updated +- Check if timestamp has been updated ```command cat /tmp/CFEngine_policy_updated ``` -* Check with Sumo Logic +- Check with Sumo Logic ![integrating-with-sumo-logic_sumo.png](integrating-with-sumo-logic_sumo.png) diff --git a/content/examples/tutorials/json-yaml-support-in-cfengine.markdown b/content/examples/tutorials/json-yaml-support-in-cfengine.markdown index 54211f241..ab3ec97d9 100644 --- a/content/examples/tutorials/json-yaml-support-in-cfengine.markdown +++ b/content/examples/tutorials/json-yaml-support-in-cfengine.markdown @@ -10,7 +10,7 @@ JSON is a well-known data language. It even has a specification (See http://json YAML is another well-known data language. It has a longer, much more complex specification (See http://yaml.org). -CFEngine has core support for JSON and YAML. Let's see what it can do. +CFEngine has core support for JSON and YAML. Let's see what it can do. ## Problem statement @@ -29,25 +29,25 @@ syntax. A new data type, the data container, was introduced in 3.6. -It's simply called `data`. The documentation with some examples is at https://cfengine.com/docs/master/reference-promise-types-vars.html#data-container-variables +It's simply called `data`. The documentation with some examples is at https://cfengine.com/docs/master/reference-promise-types-vars.html#data-container-variables ## Reading JSON There are many ways to read JSON data; here are a few: -* `readjson()`: read from a JSON file, e.g. `"mydata" data => readjson("/my/file", 100k);` -* `parsejson()`: read from a JSON string, e.g. `"mydata" data => parsejson('{ "x": "y" }');` -* `data_readstringarray()` and `data_readstringarrayidx()`: read text data from a file, split it on a delimiter, and make them into structured data. -* `mergedata()`: merge data containers, slists, and classic CFEngine arrays, e.g. `"mydata" data => mergedata(container1, slist2, array3);` +- `readjson()`: read from a JSON file, e.g. `"mydata" data => readjson("/my/file", 100k);` +- `parsejson()`: read from a JSON string, e.g. `"mydata" data => parsejson('{ "x": "y" }');` +- `data_readstringarray()` and `data_readstringarrayidx()`: read text data from a file, split it on a delimiter, and make them into structured data. +- `mergedata()`: merge data containers, slists, and classic CFEngine arrays, e.g. `"mydata" data => mergedata(container1, slist2, array3);` -`mergedata` in particular is very powerful. It can convert a slist or a classic CFEngine array to a data container easily: `"mydata" data => mergedata(myslist);` +`mergedata` in particular is very powerful. It can convert a slist or a classic CFEngine array to a data container easily: `"mydata" data => mergedata(myslist);` ## Reading YAML There are two ways to read YAML data: -* `readyaml()`: read from a YAML file, e.g. `"mydata" data => readyaml("/my/file.yaml", 100k);` -* `parseyaml()`: read from a YAML string, e.g. `"mydata" data => parseyaml('- arrayentry1');` +- `readyaml()`: read from a YAML file, e.g. `"mydata" data => readyaml("/my/file.yaml", 100k);` +- `parseyaml()`: read from a YAML string, e.g. `"mydata" data => parseyaml('- arrayentry1');` Since these functions return data containers, everything about JSON-sourced data structures applies to YAML-sourced data structures @@ -57,10 +57,10 @@ as well. To access JSON data, you can use: -* the `nth()` function to access an array element, e.g. `"myx" string => nth(container1, 0);` -* the `nth` function to access a map element, e.g. `"myx" string => nth(container1, "x");` -* the `a[b]` notation, e.g. `"myx" string => "$(container1[x])";`. You can nest, e.g. `a[b][c][0][d]`. This only works if the element is something that can be expanded in a string. So a number or a string work. A list of strings or numbers works. A key-value map under `x` won't work. -* the `getindices()` and `getvalues()` functions, just like classic CFEngine arrays +- the `nth()` function to access an array element, e.g. `"myx" string => nth(container1, 0);` +- the `nth` function to access a map element, e.g. `"myx" string => nth(container1, "x");` +- the `a[b]` notation, e.g. `"myx" string => "$(container1[x])";`. You can nest, e.g. `a[b][c][0][d]`. This only works if the element is something that can be expanded in a string. So a number or a string work. A list of strings or numbers works. A key-value map under `x` won't work. +- the `getindices()` and `getvalues()` functions, just like classic CFEngine arrays ## A full example @@ -68,10 +68,10 @@ This example can be saved and run. It will load a key-value map where the keys are class names and the values are hostname regular expressions or class names. -* if your host name is `c` or `b` or the classes `c` or `b` are defined, the `dev` class will be defined -* if your host name is `flea` or the class `flea` is defined, the `prod` class will be defined -* if your host name is `a` or the class `a` is defined, the `qa` class will be defined -* if your host name is `linux` or the class `linux` is defined, the `private` class will be defined +- if your host name is `c` or `b` or the classes `c` or `b` are defined, the `dev` class will be defined +- if your host name is `flea` or the class `flea` is defined, the `prod` class will be defined +- if your host name is `a` or the class `a` is defined, the `qa` class will be defined +- if your host name is `linux` or the class `linux` is defined, the `private` class will be defined Easy, right? @@ -139,4 +139,4 @@ and read the same container from a JSON file. ## Summary -Using JSON and YAML from CFEngine is easy and does not change how you use CFEngine. Try it out and see for yourself! +Using JSON and YAML from CFEngine is easy and does not change how you use CFEngine. Try it out and see for yourself! diff --git a/content/examples/tutorials/manage-ntp.markdown b/content/examples/tutorials/manage-ntp.markdown index b56ef68bc..9731c2d2a 100644 --- a/content/examples/tutorials/manage-ntp.markdown +++ b/content/examples/tutorials/manage-ntp.markdown @@ -6,7 +6,7 @@ sorting: 3 In this tutorial we will write a simple policy to ensure that the latest version of the NTP service is installed on your system. Once the NTP software is installed, we will extend the policy to manage the service state as well as the software configuration. -Note: For simplicity, in this tutorial we will work directly on top of the Masterfiles Policy Framework (MPF) in `/var/cfengine/masterfiles` (*masterfiles*) and we will not use version control. +Note: For simplicity, in this tutorial we will work directly on top of the Masterfiles Policy Framework (MPF) in `/var/cfengine/masterfiles` (_masterfiles_) and we will not use version control. ## Ensuring the NTP package is installed @@ -94,7 +94,7 @@ classes => results("bundle", "ntp_package_"); `classes` provide context which can help drive the logic in your policies. In this example, classes for each promise outcome are defined prefixed with `ntp_package_`, for details check out the implementation of `body classes results` in the stdlib. For example, `ntp_package_repaired` will be defined if cf-agent did not have the ntp package installed and had to install it. `ntp_package_kept` would be defined if the ntp package is already installed and `ntp_package_notkept` would be defined. -On your hub create `services/ntp.cf` inside *masterfiles* with the following content: +On your hub create `services/ntp.cf` inside _masterfiles_ with the following content: ```cf3 {file="ntp.cf"} bundle agent ntp @@ -169,7 +169,7 @@ cf-agent -KI info: Successfully installed package 'ntp' ``` -Now that we have successfully promised the package, let's move on to the *service*. +Now that we have successfully promised the package, let's move on to the _service_. ## Manage NTP service @@ -220,7 +220,7 @@ debian:: "ntp_service_name" string => "ntp"; ``` -The first thing that you will notice is that the variable declarations section has been expanded. Recall that you completed part 1 of this tutorial by creating packages promises that works across Debian and redhat. While the package name for NTP is the same between Debian and Red Hat, the service names are actually different. Therefore, classes introduced here to distinguish the service name for NTP between these two environments. The CFEngine agents automatically discover environment properties and defines [*hard classes*][language-concepts-classes-hard] that can be used - this includes classes such as `debian` and `redhat` that define the host's operating system. +The first thing that you will notice is that the variable declarations section has been expanded. Recall that you completed part 1 of this tutorial by creating packages promises that works across Debian and redhat. While the package name for NTP is the same between Debian and Red Hat, the service names are actually different. Therefore, classes introduced here to distinguish the service name for NTP between these two environments. The CFEngine agents automatically discover environment properties and defines [_hard classes_][language-concepts-classes-hard] that can be used - this includes classes such as `debian` and `redhat` that define the host's operating system. #### reports @@ -236,7 +236,7 @@ The reports promise type emits information from the agent. Most commonly and by ntp_service_repaired.inform_mode:: ``` -This line restricts the context for the promises that follow to hosts that have `ntp_service_repaired` and `inform_mode` defined. Note: `inform_mode` is defined when information level logging is requested, e.g. the `-I`, `--inform`, or `--log-level inform` options are given to `cf-agent` defined. +This line restricts the context for the promises that follow to hosts that have `ntp_service_repaired` and `inform_mode` defined. Note: `inform_mode` is defined when information level logging is requested, e.g. the `-I`, `--inform`, or `--log-level inform` options are given to `cf-agent` defined. ```cf3 "NTP service repaired"; @@ -418,7 +418,7 @@ Valid values for this attribute are `true` or `false` to instruct the agent whet perms => mog( "644", "root", "root" ), ``` -This attribute sets the permissions and ownership of the file. [`mog()`][stdlib-mog] is a `perms` body in the CFEngine standard library that sets the ```mode```, ```owner```, and ```group``` of the file. In this example, the permissions for the NTP configuration file are set to ```644``` with *owner* and *group* both assigned to ```root```. +This attribute sets the permissions and ownership of the file. [`mog()`][stdlib-mog] is a `perms` body in the CFEngine standard library that sets the `mode`, `owner`, and `group` of the file. In this example, the permissions for the NTP configuration file are set to `644` with _owner_ and _group_ both assigned to `root`. ##### handle @@ -458,7 +458,7 @@ The `edit_template_string` attribute is set to `$(config_template_string)` which template_data => mergedata( '{ "driftfile": "$(driftfile)", "servers": servers }' ), ``` -`template_data` is assigned a data container that is in this case constructed by [`mergedata()`][mergedata] so that only the necessary data is provided to the template. If `template_data` is not explicitly provided, CFEngine uses `datastate()` by default. It is considered best practice to provide explicit data as this makes it easier to delegate responsibility of the template and that data to different entities where neither are required to know anything about CFEngine itself and it's *much* more efficient to send the templating engine only the data the template actually uses. +`template_data` is assigned a data container that is in this case constructed by [`mergedata()`][mergedata] so that only the necessary data is provided to the template. If `template_data` is not explicitly provided, CFEngine uses `datastate()` by default. It is considered best practice to provide explicit data as this makes it easier to delegate responsibility of the template and that data to different entities where neither are required to know anything about CFEngine itself and it's _much_ more efficient to send the templating engine only the data the template actually uses. Note, `mergedata()` tries to expand bare values from CFEngine variables, so `servers` will expand to the entire list of servers. The result of `mergedata()` in the example is equivalent to this json: @@ -628,7 +628,7 @@ bundle agent ntp if => isvariable( "def.ntp[config][servers]" ); ``` -Notice two promises were introduced, one setting `driftfile` to the value of `$(def.ntp[config][driftfile])` if it is defined and one setting servers to the list of values for `def.ntp[config][servers]` if it is defined. [Augments][Augments] allows for variables to be set in the *def* bundle scope very early before policy is evaluated. +Notice two promises were introduced, one setting `driftfile` to the value of `$(def.ntp[config][driftfile])` if it is defined and one setting servers to the list of values for `def.ntp[config][servers]` if it is defined. [Augments][Augments] allows for variables to be set in the _def_ bundle scope very early before policy is evaluated. ### Modify and run the policy diff --git a/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown b/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown index 5c3b65445..22c972ec2 100644 --- a/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown +++ b/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown @@ -6,8 +6,8 @@ sorting: 10 ## Prerequisites -* CFEngine 3.6 Enterprise Hub -* At least one client vulnerable to CVE-2014-6271 +- CFEngine 3.6 Enterprise Hub +- At least one client vulnerable to CVE-2014-6271 ## Overview @@ -29,11 +29,11 @@ Writing inventory policy with CFEngine is just like any other CFEngine policy, except for the addition of special `meta` attributes used to augment the inventory interface. First you must know how to collect the information you want. In this case we know that a vulnerable system will have the word -*vulnerable* listed in the output of the command +_vulnerable_ listed in the output of the command `env x='() { :;}; echo vulnerable' $(bash) -c 'echo testing CVE-2014-6271'`. This bundle will check if the host is vulnerable to the CVE, define a class -*CVE_2014_6217* if it is vulnerable and augment Mission Portals Inventory +_CVE_2014_6217_ if it is vulnerable and augment Mission Portals Inventory interface in CFEngine Enterprise. ```cf3 {file="inventory_CVE_2014_6271.cf"} @@ -87,10 +87,10 @@ command. As of this writing the paths for 'env' and 'echo' are both in the standard libraries paths bundle, but 'bash' is not. Note that you may need to adjust the path to bash for your platforms. Then we run our test command and place the command output into the 'test_result' variable. Since we have no -*CVE_2014_6271* class defined yet, the next promise to set the variable +_CVE_2014_6271_ class defined yet, the next promise to set the variable 'vulnerable' to 'CVE-2014-6271' will be skipped on the first pass. Then the -classes type promise is evaluated and defines the class *CVE_2014_6271* if the -output matches the regular expression 'vulnerable.*'. Finally the reports are +classes type promise is evaluated and defines the class _CVE_2014_6271_ if the +output matches the regular expression 'vulnerable.\*'. Finally the reports are evaluated before starting the second pass. If the class 'DEBUG' or 'DEBUG_inventory_CVE_2014_6271' is set the test command output will be shown, and if the vulnerability is present agent is running in inform or verbose mode @@ -174,7 +174,7 @@ bundle agent remediate_CVE_2014_6271 For simplicity of the example this policy defines the class allow_update on hub and host001, but you could use any class that makes sense to you. If the -allow_update class is set, and the class *CVE_2014_6271* is defined (indicating +allow_update class is set, and the class _CVE_2014_6271_ is defined (indicating the host is vulnerable) then the policy ensures that bash is updated to the latest version available. diff --git a/content/examples/tutorials/reporting/_index.markdown b/content/examples/tutorials/reporting/_index.markdown index bb1c59a41..e92882431 100644 --- a/content/examples/tutorials/reporting/_index.markdown +++ b/content/examples/tutorials/reporting/_index.markdown @@ -21,19 +21,19 @@ In a CFEngine Enterprise installation, the CFEngine Server aggregates information about the environment in a centralized database. By default data is collected every 5 minutes from all bootstrapped hosts and includes information about: -* logs about promises kept, not kept and repaired -* current host contexts and classifications -* variables -* software information -* file changes +- logs about promises kept, not kept and repaired +- current host contexts and classifications +- variables +- software information +- file changes This data can be mined using SQL queries and then used for inventory management, compliance reporting, system diagnostics, and capacity planning. Access to the data is provided through: -* The [Mission Portal console][Reporting UI] -* The [Enterprise Report API][API]. +- The [Mission Portal console][Reporting UI] +- The [Enterprise Report API][API]. ### Command-Line Reporting diff --git a/content/examples/tutorials/reporting/command-line-reports.markdown b/content/examples/tutorials/reporting/command-line-reports.markdown index e840ca1f7..fb30000d7 100644 --- a/content/examples/tutorials/reporting/command-line-reports.markdown +++ b/content/examples/tutorials/reporting/command-line-reports.markdown @@ -71,6 +71,7 @@ reports: report_to_file => "/tmp/test_log"; } ``` + We can apply this idea to make more useful custom reports. In this example, the agent tests for certain software package and creates a simple HTML file of existing software: @@ -130,15 +131,14 @@ the following output: ```html {file="report.html"} -Name of this host is: atlas
-Type of this host is: linux
- -Host has software gpg
+ Name of this host is: atlas
+ Type of this host is: linux
-Host has software zip
+ Host has software gpg
-Host has software rsync
+ Host has software zip
+ Host has software rsync
``` diff --git a/content/examples/tutorials/tags.markdown b/content/examples/tutorials/tags.markdown index 537fc0dd0..67e929ee6 100644 --- a/content/examples/tutorials/tags.markdown +++ b/content/examples/tutorials/tags.markdown @@ -6,7 +6,7 @@ sorting: 14 ## Introduction -*meta tags* can be attached to any promise type using the `meta` attribute. +_meta tags_ can be attached to any promise type using the `meta` attribute. These tags are useful for cross-referencing related promises. `bundles`, `vars` and `classes` can be identified and leveraged in different ways within policy using these tags. @@ -57,28 +57,28 @@ This declares an agent bundle with a single tag. Several new functions exist to give you access to variable and class tags, and to find classes and variables with tags. -* `classesmatching`: this used to be somewhat available with the -`allclasses.txt` file. You can now call a function to get all the -defined classes, optionally filtering by name and tags. See -[classesmatching][classesmatching] +- `classesmatching`: this used to be somewhat available with the + `allclasses.txt` file. You can now call a function to get all the + defined classes, optionally filtering by name and tags. See + [classesmatching][classesmatching] -* `getvariablemetatags`: get the tags of a variable as an slist. See -[getvariablemetatags][getvariablemetatags] +- `getvariablemetatags`: get the tags of a variable as an slist. See + [getvariablemetatags][getvariablemetatags] -* `variablesmatching`: just like `classesmatching` but for variables. -See [variablesmatching][variablesmatching] +- `variablesmatching`: just like `classesmatching` but for variables. + See [variablesmatching][variablesmatching] -* `variablesmatching_as_data`: like `variablesmatching` but the matching -variables and values are returned as a merged data container. See -[variablesmatching_as_data][variablesmatching_as_data] +- `variablesmatching_as_data`: like `variablesmatching` but the matching + variables and values are returned as a merged data container. See + [variablesmatching_as_data][variablesmatching_as_data] -* `getclassmetatags`: get the tags of a class as an slist. See -[getclassmetatags][getclassmetatags] +- `getclassmetatags`: get the tags of a class as an slist. See + [getclassmetatags][getclassmetatags] -* `bundlesmatching`: find the bundles matching some tags. See -[bundlesmatching][bundlesmatching] -(the example shows how you'd find a `deprecated` bundle like -`run_deprecated` earlier). +- `bundlesmatching`: find the bundles matching some tags. See + [bundlesmatching][bundlesmatching] + (the example shows how you'd find a `deprecated` bundle like + `run_deprecated` earlier). ## Module protocol diff --git a/content/examples/tutorials/write-cfengine-policy.markdown b/content/examples/tutorials/write-cfengine-policy.markdown index 43e471ab9..542719203 100644 --- a/content/examples/tutorials/write-cfengine-policy.markdown +++ b/content/examples/tutorials/write-cfengine-policy.markdown @@ -20,7 +20,7 @@ detailed information see the Language concepts section of the Reference manual. ### Bundles -Bundles are re-usable and blocks of CFEngine policy. The following defines a *bundle* called `my_test`, and it is a bundle for the agent. +Bundles are re-usable and blocks of CFEngine policy. The following defines a _bundle_ called `my_test`, and it is a bundle for the agent. ```cf3 bundle agent my_test @@ -55,11 +55,11 @@ you want this policy to apply. For that, CFEngine has the concept of classes. ## Classes -A *class* is an identifier which is used by the agent to decide when and where a +A _class_ is an identifier which is used by the agent to decide when and where a part of a policy shall run. A class can either be user-defined, a so called soft-class, or it can be a hard class which is automatically discovered and -defined by cf-agent during each run. Popular classes include *any* which means -any or all hosts, *policy_server* which means the host is a policy server. There +defined by cf-agent during each run. Popular classes include _any_ which means +any or all hosts, _policy_server_ which means the host is a policy server. There are more than 50 hard classes, and combined with regular expressions this gives you very granular control. @@ -73,7 +73,7 @@ cf-promises --show-classes Now let's put the bundle, promise type and class components together in a final policy. As for classes we will use linux to define that the file -`/tmp/hello-world` must exists on all hosts of type *linux*: +`/tmp/hello-world` must exists on all hosts of type _linux_: ```cf3 {file="my_test.cf"} bundle agent my_test diff --git a/content/examples/tutorials/writing-and-serving-policy/_index.markdown b/content/examples/tutorials/writing-and-serving-policy/_index.markdown index 93c2e92b5..17d33022a 100644 --- a/content/examples/tutorials/writing-and-serving-policy/_index.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/_index.markdown @@ -49,7 +49,7 @@ Writing, deploying, and using CFEngine `promises` will generally follow these si 2. Create a bundle and promise in the file (see ["Hello world" policy example][Examples and tutorials#"Hello world" policy example]). 3. Save the file on the policy server somewhere under `/var/cfengine/masterfiles` (can be under a sub-directory). 4. Let CFEngine know about the `promise` on the `policy server`, generally in the file `/var/cfengine/masterfiles/promises.cf`, or a file elsewhere but referred to in `promises.cf`. - * Optional: it is also possible to call a bundle manually, using `cf-agent`. + - Optional: it is also possible to call a bundle manually, using `cf-agent`. 5. Verify the `policy file` was deployed and successfully run. @@ -57,12 +57,12 @@ See [Tutorial for running examples][Examples and tutorials#Tutorial for running ## Policy workflow -CFEngine does not make absolute choices for you, like other tools. Almost +CFEngine does not make absolute choices for you, like other tools. Almost everything about its behavior is a matter of policy and can be changed. In order to keep operations as simple as possible, CFEngine maintains a private working directory on each machine, referred to in documentation as `WORKDIR` and -in policy by the variable ```sys.workdir``` By default, this is located at +in policy by the variable `sys.workdir` By default, this is located at `/var/cfengine` or `C:\var\CFEngine`. It contains everything CFEngine needs to run. @@ -70,19 +70,19 @@ The figure below shows how decisions flow through the parts of a system. ![Policy decision and distribution flowchart](policy-decision-flow.png) -* It makes sense to have a single point of coordination. Decisions are +- It makes sense to have a single point of coordination. Decisions are therefore usually made in a single location (the Policy Definition Point). The history of decisions and changes can be tracked by a version control system of your choice (e.g. Git, Subversion, CVS etc.). -* Decisions are made by editing CFEngine's policy file `promises.cf` (or one +- Decisions are made by editing CFEngine's policy file `promises.cf` (or one of its included sub-files). This process is carried out off-line. -* Once decisions have been formalized and coded, this new policy is copied to a - decision distribution point, ```sys.masterdir``` which defaults to +- Once decisions have been formalized and coded, this new policy is copied to a + decision distribution point, `sys.masterdir` which defaults to `/var/cfengine/masterfiles` on all policy distribution servers. -* Every client machine contacts the policy server and downloads these updates. +- Every client machine contacts the policy server and downloads these updates. The policy server can be replicated if the number of clients is very large, but we shall assume here that there is only one policy server. @@ -98,11 +98,12 @@ needless fragility and keep two independent quality assurance processes apart. ## Best practices -* [Policy style guide][Policy style guide] This covers punctuation, whitespace, and other styles to remember when writing policy. +- [Policy style guide][Policy style guide] This covers punctuation, whitespace, and other styles to remember when writing policy. -* [Bundles best practices][Bundles best practices] Refer to this page as you decide when to make a bundle and when to use classes and/or variables in them. +- [Bundles best practices][Bundles best practices] Refer to this page as you decide when to make a bundle and when to use classes and/or variables in them. -* [Testing policies][Testing policies] This page describes how to locally test CFEngine and play with configuration files. +- [Testing policies][Testing policies] This page describes how to locally test CFEngine and play with configuration files. ## See also -* [Promises][Promises] + +- [Promises][Promises] diff --git a/content/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown b/content/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown index cc9d62b4f..e460f59d7 100644 --- a/content/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/authoring-policy-tools-and-workflow.markdown @@ -21,9 +21,9 @@ There are several ways to approach authoring promises and ensuring they are copi 4. When an author wants to create a new promise, or modify an existing one, they clone the same repository on GitHub so that they have a local copy on their own computer. 5. The author will make their edits or additions in their local version of the `masterfiles` repository. 6. After the author is done making their changes commit them using `git commit`. -6. After the changes are committed they are then pushed back to the remote repository on GitHub. -7. As described in step 3, CFEngine will pull any new changes that were pushed to GitHub (sometime within a five minute time interval). -8. Those changes will first exist in `masterfiles`, and then afterwards will be deployed to CFEngine hosts that are bootstrapped to the hub. +7. After the changes are committed they are then pushed back to the remote repository on GitHub. +8. As described in step 3, CFEngine will pull any new changes that were pushed to GitHub (sometime within a five minute time interval). +9. Those changes will first exist in `masterfiles`, and then afterwards will be deployed to CFEngine hosts that are bootstrapped to the hub. #### Create a Repository on GitHub for Masterfiles @@ -32,10 +32,7 @@ There are two methods possible with GitHub: one is to use the web interface at G Method One: Create Masterfiles Repository Using GitHub Web Interface 1a. In the GitHub web interface, click on the `New repository` button. -1b. Or from the `+` drop down menu on the top right hand side of the screen select `New repository`. -2. Fill in a value in the `Repository name` text entry (e.g. cfengine-masterfiles). -3. Select `private` for the type of privacy desired (`public` is also possible, but is not recommended in most situations). -4. Optionally, check the `Initialize this repository with a README` box. (not required):"" +1b. Or from the `+` drop down menu on the top right hand side of the screen select `New repository`. 2. Fill in a value in the `Repository name` text entry (e.g. cfengine-masterfiles). 3. Select `private` for the type of privacy desired (`public` is also possible, but is not recommended in most situations). 4. Optionally, check the `Initialize this repository with a README` box. (not required):"" Method Two: Create Masterfiles Repository Using the GitHub Application @@ -46,6 +43,7 @@ Method Two: Create Masterfiles Repository Using the GitHub Application 5. Click on the "Create" button at the bottom of the screen. A new repository will be created in your local GitHub folder. #### Initialize Git Repository in Masterfiles on the Hub + ```bash cd /var/cfengine/masterfiles echo cf_promises_validated >> .gitignore @@ -55,6 +53,7 @@ git commit -m "First commit" git remote add origin https://github.com/GitUserName/cfengine-masterfiles.git git push -u origin master ``` + **Note:** `cf_promises_validated` and `cf_promises_release_id` should be explicitly excluded from VCS as shown above. They are generated files and involved in controlling policy updates. If these files are checked into the repository it can create issues with policy distribution. Using the above steps on a private repository will fail with a 403 error. There are different approaches to deal with this: @@ -87,6 +86,7 @@ B) Or, change the remote url to `https://GitUserName@password:github.com/GitUser ```command cd /var/cfengine/masterfiles ``` + 2. Create the remote using the following pattern: ```command @@ -98,7 +98,8 @@ git remote add upstream ssh://git@github.com/GitUserName/cfengine-masterfiles.gi ```command git remote -v ``` - * You will see the remote definition in a list alongside any other previously defined remote entries. + + * You will see the remote definition in a list alongside any other previously defined remote entries. #### Add a Promise that Pulls Changes to Masterfiles on the Hub from Masterfiles on GitHub diff --git a/content/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown b/content/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown index faef1fdb8..488f8ae51 100644 --- a/content/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/bundles-best-practices.markdown @@ -17,36 +17,36 @@ understand what they are about. For example: -* app_mail_postfix -* app_mail_mailman -* app_web_apache -* app_web_squid -* app_web_php -* app_db_mysql -* garbage_collection -* security_check_files -* security_check_processes -* system_name_resolution -* system_xinetd -* system_root_password -* system_processes -* system_files -* win_active_directory -* win_registry -* win_services +- app_mail_postfix +- app_mail_mailman +- app_web_apache +- app_web_squid +- app_web_php +- app_db_mysql +- garbage_collection +- security_check_files +- security_check_processes +- system_name_resolution +- system_xinetd +- system_root_password +- system_processes +- system_files +- win_active_directory +- win_registry +- win_services ### When to make a bundle Put items into a single bundle if: -* They belong to the same conceptual aspect of system administration. -* They do not need to be switched on or off independently. +- They belong to the same conceptual aspect of system administration. +- They do not need to be switched on or off independently. Put items into different bundles if: -* All of the promises in one bundle need to the checked before all of the -promises in another bundle. -* You need to re-use the promises with different parameters. +- All of the promises in one bundle need to the checked before all of the + promises in another bundle. +- You need to re-use the promises with different parameters. In general, keep the number of bundles to a minimum. This is a knowledge-management issue. Clarity comes from differentiation, but only if the number of items is small. @@ -97,18 +97,18 @@ reports: ### When to use classes in common bundles -* When you need to use them in multiple bundles (because classes defined in common bundles -have global scope). +- When you need to use them in multiple bundles (because classes defined in common bundles + have global scope). ### When to use variables in common bundles -* For rationality, if the variable does not belong to any particular bundle, because it is -used elsewhere. (Qualified variable names such as `$(mybundle.myname)` are always globally -accessible, so this is a cosmetic issue.) +- For rationality, if the variable does not belong to any particular bundle, because it is + used elsewhere. (Qualified variable names such as `$(mybundle.myname)` are always globally + accessible, so this is a cosmetic issue.) ### When to use variables in local bundles -* If they are not needed outside the bundles. -* If they are used for iteration (without qualified scope). -* If they are tied to a specific aspect of system maintenance represented by the bundle, so -that accessing `$(bundle.var)` adds clarity. +- If they are not needed outside the bundles. +- If they are used for iteration (without qualified scope). +- If they are tied to a specific aspect of system maintenance represented by the bundle, so + that accessing `$(bundle.var)` adds clarity. diff --git a/content/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown b/content/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown index 94fa21398..2522a2dea 100644 --- a/content/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/controlling-frequency.markdown @@ -61,13 +61,13 @@ a way that you can start several CFEngine components simultaneously without them interfering with each other. You can control two things about each kind of action in CFEngine: -* `ifelapsed` - The minimum time (in minutes) which should have passed since the +- `ifelapsed` - The minimum time (in minutes) which should have passed since the last time that promise was verified. It will not be executed again until this amount of time has elapsed. If the value is `0` the promise has no lock and will always be executed when in context. Additionally, a value of `0` disables function caching. Default time is `1` minute. -* `expireafter` - The maximum amount (in minutes) of time `cf-agent` should wait +- `expireafter` - The maximum amount (in minutes) of time `cf-agent` should wait for an old instantiation to finish before killing it and starting again. You can think about [`expireafter`][cf-agent#expireafter] as a timeout to use when a promise verification may involve an operation that could wait indefinitely. @@ -124,10 +124,10 @@ bundle agent __main__ **Note:** -* Promise locks are ignored when CFEngine is run with the `--no-lock` or `-K` +- Promise locks are ignored when CFEngine is run with the `--no-lock` or `-K` option, e.g. a common **manual** execution of the agent, `cf-agent -KI` would not respect promises that are locked from a recent execution. -* Locks are purged based on database utilization and age in order to maintain +- Locks are purged based on database utilization and age in order to maintain the integrity and health of the underlying lock database. **See also:** [cf_lock.lmdb][CFEngine directory structure#state/cf_lock.lmdb] diff --git a/content/examples/tutorials/writing-and-serving-policy/editors.markdown b/content/examples/tutorials/writing-and-serving-policy/editors.markdown index 8655458b3..84fc7f662 100644 --- a/content/examples/tutorials/writing-and-serving-policy/editors.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/editors.markdown @@ -33,7 +33,7 @@ Microsoft VS Code users have syntax highlighting thanks to AZaugg. Install the s ## Sublime Text Sublime Text 2 and 3 users have syntax highlighting and snippets thanks to Valery Astraverkhau. Get the syntax highlighting and snippets from his github repository. Aki Vanhatalo has contributed a beautifier to automatically re-indent policy in Sublime Text. - Sublime Screenshot +Sublime Screenshot ![Sublime Text](guide-writing-and-serving-policy-editors-sublime-text.jpg) @@ -53,7 +53,7 @@ This extension is available in both [Atom (discontinued)](https://github.blog/ne ## Eclipse -Interested in syntax highlighting for your CFEngine policy in Eclipse? Try this contributed syntax definition. +Interested in syntax highlighting for your CFEngine policy in Eclipse? Try this contributed syntax definition. Want more out of your Eclipse & CFEngine experience? Itemis Xtext expert Boris Holzer developed a CFEngine workbench for Eclipse. They even published a brief screen-cast highlighting many of its features. For more information about their workbench please contact them using this form. diff --git a/content/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction.markdown b/content/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction.markdown index 6832e9608..9418e12c7 100644 --- a/content/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/policy-layers-abstraction.markdown @@ -12,7 +12,7 @@ CFEngine is designed to handle high level simplicity (without sacrificing low level capability) by working with configuration patterns. After all, configuration is all about promising consistent patterns in the resources of the system. Lists, for instance, are a particularly common kind of pattern: -*for each of the following... make a similar promise*. There are several ways +_for each of the following... make a similar promise_. There are several ways to organize patterns, using containers, lists and associative arrays. ## Menu level diff --git a/content/examples/tutorials/writing-and-serving-policy/policy-style.markdown b/content/examples/tutorials/writing-and-serving-policy/policy-style.markdown index 77cc87660..532cbabae 100644 --- a/content/examples/tutorials/writing-and-serving-policy/policy-style.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/policy-style.markdown @@ -10,19 +10,19 @@ guide. ## Style summary -* One indent = 2 spaces -* Avoid letting line length surpass 80 characters. - * When writing policy for documentation / blog posts / tutorials: +- One indent = 2 spaces +- Avoid letting line length surpass 80 characters. + - When writing policy for documentation / blog posts / tutorials: Try to split up lines and fit within 45 characters in general, as long as it's not too problematic. (This will avoid horizontal scrolling on small windows and mobile). -* Add one indentation level per nesting of logic you are inside (promise type, class guard, promise, parenthesis, curly brace); - * **Macros (`@if` etc.):** 0 indents (never indented) - * **Promise types:** 1 indent - * **Class guards:** +1 indent (2 indents in bundle, 1 indent in body) - * **Promisers:** +1 indent (2 or 3 indents, depending on whether there is a class guard or not) - * **Promise attributes:** +1 indent from promiser (3 or 4 indents). - * **Parentheses:** +1 indent (function calls or bundle invokations across multiple lines). - * **Curly braces:** +1 indent (slists / JSON / data containers). +- Add one indentation level per nesting of logic you are inside (promise type, class guard, promise, parenthesis, curly brace); + - **Macros (`@if` etc.):** 0 indents (never indented) + - **Promise types:** 1 indent + - **Class guards:** +1 indent (2 indents in bundle, 1 indent in body) + - **Promisers:** +1 indent (2 or 3 indents, depending on whether there is a class guard or not) + - **Promise attributes:** +1 indent from promiser (3 or 4 indents). + - **Parentheses:** +1 indent (function calls or bundle invokations across multiple lines). + - **Curly braces:** +1 indent (slists / JSON / data containers). ## Promise ordering @@ -33,7 +33,7 @@ The other is reader optimized where promises are written in the order they make sense to the reader. Both styles have their merits, but there seems to be a trend toward the reader optimized style. -1) Normal Order +1. Normal Order Here is an example of a policy written in the Normal Order. Note how `packages` are listed after `files`. This could confuse a novice who @@ -74,7 +74,7 @@ bundle agent main } ``` -2) Reader Optimized +2. Reader Optimized Here is an example of a policy written to be optimized for the reader. Note how packages are listed before files in the order which users @@ -308,7 +308,7 @@ when debugging a large policy set. Promise handles uniquely identify a promise within a policy. We suggest a simple naming scheme of `bundle_name_promise_type_class_restriction_promiser` to keep handles unique and -easily identifiable. Often it may be easier to omit the handle. +easily identifiable. Often it may be easier to omit the handle. ```cf3 bundle agent example @@ -380,8 +380,8 @@ Naming conventions can also help to provide clarity. ### Snakecase -Words delimited by an underscore. This style is prevalant for *variables*, -*classes*, *bundle* and *body* names in the Masterfiles Policy Framework. +Words delimited by an underscore. This style is prevalant for _variables_, +_classes_, _bundle_ and _body_ names in the Masterfiles Policy Framework. {{< CFEngine_include_example(style_snake_case.cf) >}} @@ -496,13 +496,14 @@ bundle agent old }; } ``` + ## Tooling Currently, there is no canonical policy linting or reformatting tool. There are a few different tools that can be useful apart from an [editor with syntax support][Editors] for achieving regular formatting. ### cf-promises -`cf-promises` can output the parsed policy using the ```--policy-output-format``` option. Beware, this will strip macros as they are done during parse time. +`cf-promises` can output the parsed policy using the `--policy-output-format` option. Beware, this will strip macros as they are done during parse time. Example policy: @@ -526,7 +527,7 @@ bundle agent satellite_bootstrap_main } ``` -Output the parsed policy in ```cf``` format: +Output the parsed policy in `cf` format: ```command cf-promises -f /tmp/example.cf --policy-output-format cf diff --git a/content/examples/tutorials/writing-and-serving-policy/testing-policies.markdown b/content/examples/tutorials/writing-and-serving-policy/testing-policies.markdown index 68a11d4ae..cb59f0c6c 100644 --- a/content/examples/tutorials/writing-and-serving-policy/testing-policies.markdown +++ b/content/examples/tutorials/writing-and-serving-policy/testing-policies.markdown @@ -31,6 +31,7 @@ cp /var/cfengine/inputs/*.cf ~/.cfagent/inputs You can test the software and play with configuration files by editing the basic directly in the `~/.cfagent/inputs` directory. For example, try the following: + ```console ~/.cfagent/bin/cf-promises ~/.cfagent/bin/cf-promises --verbose diff --git a/content/getting-started/developing-modules.markdown b/content/getting-started/developing-modules.markdown index cdc0311fc..63f9a1ceb 100644 --- a/content/getting-started/developing-modules.markdown +++ b/content/getting-started/developing-modules.markdown @@ -13,9 +13,9 @@ _Validation_ should check that the correct attributes are used, and any other co _Evaluation_ happens after successful _Validation_, and actually performs actions / makes changes to the system. When implementing a promise type for CFEngine, there are 3 outcomes you need to understand: -* `Result.KEPT` - The module detected that no changes are necessary, the actual state of the system is already consistent with the desired state -* `Result.REPAIRED` - The module detected that changes have to be made, and successfully completed all of them -* `Result.NOT_KEPT` - The module failed to make the necessary changes +- `Result.KEPT` - The module detected that no changes are necessary, the actual state of the system is already consistent with the desired state +- `Result.REPAIRED` - The module detected that changes have to be made, and successfully completed all of them +- `Result.NOT_KEPT` - The module failed to make the necessary changes ## The template @@ -72,9 +72,9 @@ https://github.com/cfengine/promise-type-template Take a look at these important files: -* `git_example.py` - The module code itself. This is where you will work the most, changing what the promise type does, implementing functionality, fixing bugs, etc. -* `cfbs.json` - Metadata about the module(s). Most importantly, the `provides` key has the information needed for `cfbs add`, and subsequently `cfbs build` to work. -* `enable.cf` - The snippet of policy that needs to be included to enable your promise type. +- `git_example.py` - The module code itself. This is where you will work the most, changing what the promise type does, implementing functionality, fixing bugs, etc. +- `cfbs.json` - Metadata about the module(s). Most importantly, the `provides` key has the information needed for `cfbs add`, and subsequently `cfbs build` to work. +- `enable.cf` - The snippet of policy that needs to be included to enable your promise type. Start by editing `cfbs.json`, at least changing the `repo` and `by` URLs. @@ -133,8 +133,8 @@ https://github.com/cfengine/build-index/blob/master/CONTRIBUTING.md There are several places to look for more information or inspiration when writing modules: -* [The real git promise type code](https://github.com/cfengine/modules/tree/c3b7329b240cf7ad062a0a64ee8b607af2cb912a/promise-types/git/) -* [HTTP promise type module](https://github.com/cfengine/modules/tree/c861789d4b376147d904fccd76963a92e65eaa97/promise-types/http/) -* [CFEngine custom promise type specification](./reference-promise-types-custom.html) -* [Blog post: How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) -* [Blog post: How to implement CFEngine Custom Promise types in Bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) +- [The real git promise type code](https://github.com/cfengine/modules/tree/c3b7329b240cf7ad062a0a64ee8b607af2cb912a/promise-types/git/) +- [HTTP promise type module](https://github.com/cfengine/modules/tree/c861789d4b376147d904fccd76963a92e65eaa97/promise-types/http/) +- [CFEngine custom promise type specification](./reference-promise-types-custom.html) +- [Blog post: How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) +- [Blog post: How to implement CFEngine Custom Promise types in Bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) diff --git a/content/getting-started/installation/_index.markdown b/content/getting-started/installation/_index.markdown index a5f77c356..204e0d425 100644 --- a/content/getting-started/installation/_index.markdown +++ b/content/getting-started/installation/_index.markdown @@ -25,10 +25,10 @@ We will use an Ubuntu 20.04 Linux virtual machine as the CFEngine Hub, and we wi If you've never set up a virtual machine (VM) before, these are some easy ways: -* Cloud: Create a VM in Digital Ocean, AWS, or any other cloud vendor. **(Recommended)** -* Mac OS: Install and run Vagrant and Virtual Box. -* Linux: Install and run Vagrant and libvirt. -* Windows: Use Windows Subsystem for Linux (WSL). +- Cloud: Create a VM in Digital Ocean, AWS, or any other cloud vendor. **(Recommended)** +- Mac OS: Install and run Vagrant and Virtual Box. +- Linux: Install and run Vagrant and libvirt. +- Windows: Use Windows Subsystem for Linux (WSL). We recommend using Digital Ocean because it is very easy to use the GUI, and spawn a virtual without installing something locally. However, since it requires you to create an account, some users might prefer to install virtualization software and run everything themself. @@ -173,10 +173,10 @@ ssh root@192.168.56.2 -C "echo hello" If you see `hello` printed, it worked! If not, these are some of the more common error scenarios: -* If it prints `Connection refused`, it might be because you just started the machine, wait a bit and try again. -* If it hangs for many seconds, it might mean that you typed the wrong IP address (`Ctrl + C` to interrupt). -* If it prints `Connection timed out`, you are most likely using the wrong IP address. -* If it gives any other errors, such as `Permission denied (publickey)` you may be using the wrong user / SSH key or IP address. Double check and try again. +- If it prints `Connection refused`, it might be because you just started the machine, wait a bit and try again. +- If it hangs for many seconds, it might mean that you typed the wrong IP address (`Ctrl + C` to interrupt). +- If it prints `Connection timed out`, you are most likely using the wrong IP address. +- If it gives any other errors, such as `Permission denied (publickey)` you may be using the wrong user / SSH key or IP address. Double check and try again. After you see ssh working, save the host in `cf-remote` so you can copy-paste our later commands: diff --git a/content/getting-started/installation/general-installation/_index.markdown b/content/getting-started/installation/general-installation/_index.markdown index cb0120b44..92c948a02 100644 --- a/content/getting-started/installation/general-installation/_index.markdown +++ b/content/getting-started/installation/general-installation/_index.markdown @@ -21,26 +21,26 @@ Note: See [Installing Community][Installing Community] for the community version 1. On the designated Policy Server, install the `cfengine-nova-hub` package: - ``` - [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm - [Debian/Ubuntu] # apt -y install /path/to/.deb - ``` + ``` + [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm + [Debian/Ubuntu] # apt -y install /path/to/.deb + ``` 2. On each Host, install the `cfengine-nova` package: - ``` - [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm - [Debian/Ubuntu] # apt -y install /path/to/.deb - ``` + ``` + [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm + [Debian/Ubuntu] # apt -y install /path/to/.deb + ``` Note: Install actions logged to `/var/logs/cfengine-install.log`. ## Bootstrap -Bootstrapping a client means to configure it initially. With CFEngine, the default bootstrap: +Bootstrapping a client means to configure it initially. With CFEngine, the default bootstrap: -* records the server's address (accessible as `sys.policy_hub`) and public key, and gives the server the client's key to establish trust (see [Bootstrapping][Client server communication#Bootstrapping]) -* copies **all** the contents of `/var/cfengine/masterfiles` on the policy server (AKA `sys.masterdir`) to `/var/cfengine/inputs` (AKA `sys.inputdir`). See `update.cf` for details. +- records the server's address (accessible as `sys.policy_hub`) and public key, and gives the server the client's key to establish trust (see [Bootstrapping][Client server communication#Bootstrapping]) +- copies **all** the contents of `/var/cfengine/masterfiles` on the policy server (AKA `sys.masterdir`) to `/var/cfengine/inputs` (AKA `sys.inputdir`). See `update.cf` for details. Run the bootstrap command, **first** on the policy server: @@ -123,13 +123,13 @@ See: [What steps should I take after installing CFEngine Enterprise?][FAQ#What s Although most install procedures follow the same general workflow, there are several ways of installing CFEngine depending on your environment and which version of CFEngine you are using. -* [Installing Enterprise for production][Installing Enterprise for production] -* Install and test the latest version using our [native version][Installing Enterprise 25 Free], for free! -* Installing CFEngine on virtual machine instances using [Amazon Web Services' (AWS) EC2 service][Using Amazon Web Services] - * This is especially useful for people running Windows on their workstation or laptop. -* Install and test the latest version using our pre-packaged [Vagrant environment][Using Vagrant] -* [Installing CFEngine Community Edition][Installing Community] +- [Installing Enterprise for production][Installing Enterprise for production] +- Install and test the latest version using our [native version][Installing Enterprise 25 Free], for free! +- Installing CFEngine on virtual machine instances using [Amazon Web Services' (AWS) EC2 service][Using Amazon Web Services] + - This is especially useful for people running Windows on their workstation or laptop. +- Install and test the latest version using our pre-packaged [Vagrant environment][Using Vagrant] +- [Installing CFEngine Community Edition][Installing Community] ## Next steps -* Learn about [Writing and serving policy][Writing and serving policy] +- Learn about [Writing and serving policy][Writing and serving policy] diff --git a/content/getting-started/installation/general-installation/common_next_steps.include.markdown b/content/getting-started/installation/general-installation/common_next_steps.include.markdown index 73c65b590..7818cb84e 100644 --- a/content/getting-started/installation/general-installation/common_next_steps.include.markdown +++ b/content/getting-started/installation/general-installation/common_next_steps.include.markdown @@ -1,11 +1,11 @@ # Next steps -* [Writing and serving policy][Writing and serving policy] -* [Examples and tutorials][Examples and tutorials] -* ["Hello World" Tutorial][Examples and tutorials#Tutorial for running examples] +- [Writing and serving policy][Writing and serving policy] +- [Examples and tutorials][Examples and tutorials] +- ["Hello World" Tutorial][Examples and tutorials#Tutorial for running examples] ## See also -* [General installation][General installation] -* [Post-installation configuration][General installation#Post-installation configuration] -* [FAQ][FAQ] +- [General installation][General installation] +- [Post-installation configuration][General installation#Post-installation configuration] +- [FAQ][FAQ] diff --git a/content/getting-started/installation/general-installation/installation-community-containerized.markdown b/content/getting-started/installation/general-installation/installation-community-containerized.markdown index e0bbcbc76..4f84e52d9 100644 --- a/content/getting-started/installation/general-installation/installation-community-containerized.markdown +++ b/content/getting-started/installation/general-installation/installation-community-containerized.markdown @@ -14,24 +14,27 @@ Both the containers will run **_ubi9-init_** images and communicate on a contain Upon completion, you are ready to start working with CFEngine. ## Requirements -* 1G+ disk space -* 1G+ memory -* Working [Docker Engine](https://docs.docker.com/engine/) or [Podman](https://podman.io/) setups on a supported [x86_64](https://en.wikipedia.org/wiki/X86-64) platform. + +- 1G+ disk space +- 1G+ memory +- Working [Docker Engine](https://docs.docker.com/engine/) or [Podman](https://podman.io/) setups on a supported [x86_64](https://en.wikipedia.org/wiki/X86-64) platform. **Note**: This document considers [Docker Engine](https://docs.docker.com/engine/) for all examples. Use of [Podman](https://podman.io/) shall be similar with adequate adaptations. (_Ref_: [Emulating Docker CLI with Podman](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman)). ## Overview + 1. Installing container engine 2. Preparing CFEngine hub in container 3. Preparing CFEngine host in container 4. Using docker compose - 1. Preparing container image for CFEngine - 2. Using docker compose service + 1. Preparing container image for CFEngine + 2. Using docker compose service 5. Glossary 6. References ## Installing container engine + **Ref**: [Install Docker Engine](https://docs.docker.com/engine/install/) OR @@ -40,6 +43,7 @@ OR (_Optionally_: [Emulating Docker CLI with Podman](https://podman-desktop.io/docs/migrating-from-docker/emulating-docker-cli-with-podman)) ## Preparing CFEngine hub in container + Run the container with systemd ```command @@ -65,6 +69,7 @@ docker exec cfengine-hub bash -c "/usr/local/sbin/cf-agent --bootstrap \$(ip -4 ``` ## Preparing CFEngine host in container + The procedure to setup **cfengine-host** is similar to the **cfengine-hub** deployment. The changes are to name of the host container for better identification and bootstrap IP of the **cfengine-hub**. ```command @@ -84,6 +89,7 @@ docker exec cfengine-host bash -c "cf-remote install --edition community --clien ``` ### Bootstrap cfengine-host to the policy server container. + Find IP address of **cfengine-hub**: ```command @@ -97,7 +103,9 @@ docker exec cfengine-host bash -c "/usr/local/sbin/cf-agent --bootstrap ${CFENGI ``` ## Using docker compose + ### Preparing container image for CFEngine + Create a `Dockerfile` with following contents: ```Dockerfile @@ -151,6 +159,7 @@ cfengine lts About an hour ago 302MB ``` ### Using docker compose service + Create a `compose.yaml` file with following contents: ```yaml {file="compose.yaml"} @@ -199,6 +208,7 @@ Validate the `compose.yaml` file ```command docker compose -f compose.yaml config 1>/dev/null ``` + **Note**: No output means valid yaml file. Start service cfengine-demo @@ -272,6 +282,7 @@ docker compose -f compose.yaml down ``` ## Glossary + - [Hub](https://docs.cfengine.com/docs/3.24/overview-glossary.html#hub) - [Host](https://docs.cfengine.com/docs/3.24/overview-glossary.html#host) - [Client](https://docs.cfengine.com/docs/3.24/overview-glossary.html#client) @@ -282,6 +293,7 @@ docker compose -f compose.yaml down - [Policy server](https://docs.cfengine.com/docs/3.24/overview-glossary.html#policy-server) ## References + - [Dockerfile](https://docs.docker.com/reference/dockerfile/) - [Docker compose file](https://docs.docker.com/reference/compose-file/) - [RedHat Universal Base Image (UBI)](https://www.redhat.com/en/blog/introducing-red-hat-universal-base-image) diff --git a/content/getting-started/installation/general-installation/installation-community.markdown b/content/getting-started/installation/general-installation/installation-community.markdown index bbf99e516..d5a73960b 100644 --- a/content/getting-started/installation/general-installation/installation-community.markdown +++ b/content/getting-started/installation/general-installation/installation-community.markdown @@ -9,13 +9,13 @@ deb packages for Ubuntu, Debian, Redhat, CentOS, and SUSE. It also provides instructions for the following: -* **Install CFEngine on a policy server (hub) and on a Host (client).** -A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. -Hosts are clients that retrieve and execute promises. -* **Bootstrap the policy server to itself and then bootstrap the Host(s) to the Policy Server.** -Bootstrapping establishes a trust relationship between the Policy Server -and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. -Bootstrapping completes the installation process. +- **Install CFEngine on a policy server (hub) and on a Host (client).** + A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. + Hosts are clients that retrieve and execute promises. +- **Bootstrap the policy server to itself and then bootstrap the Host(s) to the Policy Server.** + Bootstrapping establishes a trust relationship between the Policy Server + and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. + Bootstrapping completes the installation process.
## Quick setup with cf-remote @@ -29,6 +29,7 @@ For example, here we install CFEngine Community {{site.cfengine.branch}}.{{site. ```command cf-remote --version={{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}} install --edition community --clients 192.168.56.13,192.168.56.14 --bootstrap 192.168.56.13 ``` + ## 1. Download packages Packages can be downloaded from the [community download page][community download page] or using `cf-remote`. @@ -50,7 +51,7 @@ Copied to '/tmp/cfengine-community_3.24.1-1.ubuntu24_amd64.deb' (Checksum OK). ## 2. Install CFEngine on a policy server -Install the package on a machine designated as a Policy Server. A Policy Server is a CFEngine instance that contains promises (business policy) +Install the package on a machine designated as a Policy Server. A Policy Server is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. Hosts are instances (clients) that retrieve and execute promises. Choose the right command for your operating system: diff --git a/content/getting-started/installation/general-installation/installation-coreos.markdown b/content/getting-started/installation/general-installation/installation-coreos.markdown index ebbfee648..021a0da02 100644 --- a/content/getting-started/installation/general-installation/installation-coreos.markdown +++ b/content/getting-started/installation/general-installation/installation-coreos.markdown @@ -16,15 +16,15 @@ Download the file-system image package for CoreOS from the [Enterprise Downloads 1. On the CoreOS Host, extract the `fs-img-pkg.tar.gz` archive: - ```command - tar xvf cfengine-nova-{{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}}-{{site.cfengine.latest_package_build}}.x86_64.fs-img.pkg.tar.gz - ``` + ```command + tar xvf cfengine-nova-{{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}}-{{site.cfengine.latest_package_build}}.x86_64.fs-img.pkg.tar.gz + ``` 2. On the CoreOS Host, run the install script: - ```command - sudo ./cfengine-nova-{{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}}-{{site.cfengine.latest_package_build}}.x86_64.fs-img.pkg/install.sh - ``` + ```command + sudo ./cfengine-nova-{{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}}-{{site.cfengine.latest_package_build}}.x86_64.fs-img.pkg/install.sh + ``` Note: Install actions logged to `/var/log/CFEngine-Install.log`. diff --git a/content/getting-started/installation/general-installation/installation-enterprise-free-aws-rhel.markdown b/content/getting-started/installation/general-installation/installation-enterprise-free-aws-rhel.markdown index b16cea6a4..9e946fe55 100644 --- a/content/getting-started/installation/general-installation/installation-enterprise-free-aws-rhel.markdown +++ b/content/getting-started/installation/general-installation/installation-enterprise-free-aws-rhel.markdown @@ -22,41 +22,42 @@ This tutorial will cover the following steps: ### Configure 2 RHEL virtual machine instances in AWS -* Login to AWS. -* Under `Create Instance` click on `Launch Instance`. -* On the line `Red Hat Enterprise Linux 64 Bit Free tier eligible` press the `Select` button. -* On the `Choose Instance Type` screen ensure the `Micro Instances` tab on the left is selected. +- Login to AWS. +- Under `Create Instance` click on `Launch Instance`. +- On the line `Red Hat Enterprise Linux 64 Bit Free tier eligible` press the `Select` button. +- On the `Choose Instance Type` screen ensure the `Micro Instances` tab on the left is selected. ### Configure instance details -* Press `Next: Configure instance details`. -* On the `Configure instance details` screen change the number of instances to 2. -* Leave `Network` as the default. -* `Subnet` can be `No preference`. -* Ensure `Public IP` is checked. -* Leave all else at their default values. +- Press `Next: Configure instance details`. +- On the `Configure instance details` screen change the number of instances to 2. +- Leave `Network` as the default. +- `Subnet` can be `No preference`. +- Ensure `Public IP` is checked. +- Leave all else at their default values. ### Review and launch -* Click `Review and launch`. -* Make a note of `Security group` name on the `Review Instance Launch` screen. -* Click `Launch`. -* Select `Create a new key` pair in the first drop down menu. -* Enter anything as the `Key pair name`. -* Click the `Download Key Pair` button and save the .pem file to your local computer. -* After the .pem file is saved click the `Launch Instance` button. -* On the `Launch Status` screen click the `View Instances` button. + +- Click `Review and launch`. +- Make a note of `Security group` name on the `Review Instance Launch` screen. +- Click `Launch`. +- Select `Create a new key` pair in the first drop down menu. +- Enter anything as the `Key pair name`. +- Click the `Download Key Pair` button and save the .pem file to your local computer. +- After the .pem file is saved click the `Launch Instance` button. +- On the `Launch Status` screen click the `View Instances` button. ### Configure the security group -* On the left hand side of the AWS console click `NETWORK & SECURITY > Security Groups` -* Remembering the `Security group` name from earlier, click on the appropriate line item in the list. -* Below the list of security group names will display details for the current security group. -* Click the `Inbound` tab. -* Click "Edit" button. A popup window will appear with "SSH" rule already present. -* Click the `+Add Rule` button. Select `HTTP` from the drop-down list. Click "Add Rule" button again. -* Select `Custom TCP rule` and enter `5308` in the `Port range` text entry. Select "Custom IP" from the drop-down menu in the "Source" column. -* Copy the "Group ID" from the line containing your "Group Name" and copy the "Group ID" into the text entry in the last column. Click "Save." -* Click the "Edit" button again. On the "Custom TCP" Rule, select "Anywhere" from the "Source" drop-down list. Click "Save." +- On the left hand side of the AWS console click `NETWORK & SECURITY > Security Groups` +- Remembering the `Security group` name from earlier, click on the appropriate line item in the list. +- Below the list of security group names will display details for the current security group. +- Click the `Inbound` tab. +- Click "Edit" button. A popup window will appear with "SSH" rule already present. +- Click the `+Add Rule` button. Select `HTTP` from the drop-down list. Click "Add Rule" button again. +- Select `Custom TCP rule` and enter `5308` in the `Port range` text entry. Select "Custom IP" from the drop-down menu in the "Source" column. +- Copy the "Group ID" from the line containing your "Group Name" and copy the "Group ID" into the text entry in the last column. Click "Save." +- Click the "Edit" button again. On the "Custom TCP" Rule, select "Anywhere" from the "Source" drop-down list. Click "Save." ## Accessing the virtual machines using SSH @@ -66,32 +67,32 @@ See: [Quick-Start Guide to Using PuTTY][Quick-Start Guide to Using PuTTY] ### Install the firewall -* Ensure you are logged into both virtual machines. -* In both enter `sudo yum install system-config-firewall` to install. -* Hit 'y' if prompted. +- Ensure you are logged into both virtual machines. +- In both enter `sudo yum install system-config-firewall` to install. +- Hit 'y' if prompted. ### Configure the firewall on the policy server (AKA hub) The following steps are only necessary for one of the two virtual machines, the one that is designated as the policy server; these steps can be omitted on the second (client machine). Note that CFEngine refers to a client machine by the name `Host`: -* When system-config-firewall is installed, enter `sudo system-config-firewall` -* In the `Firewall Configuration` screen use the `Tab` key to go to Customize. -* Hit the `Enter` key. Below is the `Firewall Configuration` window that comes up: +- When system-config-firewall is installed, enter `sudo system-config-firewall` +- In the `Firewall Configuration` screen use the `Tab` key to go to Customize. +- Hit the `Enter` key. Below is the `Firewall Configuration` window that comes up: ![The firewall Configuration window](Installing-CFE-on-AWS-8.png) #### Open port 80 (HTTPD) -* On the `Trusted Services` screen, scroll down to `WWW (HTTP)`, AKA port 80. -* Hit the `Space Bar` to toggle the `WWW` entry (i.e. ensure it is on, showing an asterisk beside the name). +- On the `Trusted Services` screen, scroll down to `WWW (HTTP)`, AKA port 80. +- Hit the `Space Bar` to toggle the `WWW` entry (i.e. ensure it is on, showing an asterisk beside the name). #### Open port 5308 (CFEngine) -* Hit the `Tab` key again until `Forward` is highlighted, then hit `Enter`. -* Hit the `Tab` key until `Add` is highlighted, then hit `Enter`. -* Enter `5308` in the `Port` section. -* Hit the `Tab` key and enter `tcp` in the `Protocol` section. -* Hit the `Tab` key until OK is highlighted, and hit `Enter`. +- Hit the `Tab` key again until `Forward` is highlighted, then hit `Enter`. +- Hit the `Tab` key until `Add` is highlighted, then hit `Enter`. +- Enter `5308` in the `Port` section. +- Hit the `Tab` key and enter `tcp` in the `Protocol` section. +- Hit the `Tab` key until OK is highlighted, and hit `Enter`. ![Configuring a forward](Installing-CFE-on-AWS-9.png) @@ -100,14 +101,15 @@ Then the `Tab` key is used to highlight the `OK` button, and the user presses `E #### Wrapping up firewall configuration -* Hit the `Tab` key until `Close` is highlighted, and hit `Enter`. -* Hit the `Tab` key or arrow keys until `OK` is highlighted, and hit `Enter`. +- Hit the `Tab` key until `Close` is highlighted, and hit `Enter`. +- Hit the `Tab` key or arrow keys until `OK` is highlighted, and hit `Enter`. #### Disabling firewall on a host (Warning: Only do this if absolutely necessary) For the second virtual machine, which is the client machine (also called `host`), you may need to do the following if you see an error when bootstrapping this virtual machine in later steps: -* In the `Firewall Configuration` screen use the `Tab` key to go to Firewall. -* Turn off the firewall by toggling the entry with the `Space` bar. + +- In the `Firewall Configuration` screen use the `Tab` key to go to Firewall. +- Turn off the firewall by toggling the entry with the `Space` bar. Note: Turning off the firewall in a production environment is considered unsafe. @@ -115,10 +117,10 @@ Note: Turning off the firewall in a production environment is considered unsafe. We ready now ready to install the CFEngine software on both the server and client virtual machines. These also referred to as the "hub" and "host" machines, respectively. During the course of the instructions outlined in this guide, you will perform the following tasks: -* Install CFEngine Enterprise onto a Policy Server and onto Hosts. A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. Hosts are clients that retrieve and execute promises. -* Bootstrap the policy server to itself and then bootstrap each of the Hosts to the Policy Server. Bootstrapping establishes a trust relationship between the Policy Server and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. Bootstrapping completes the installation process. -* Log in to the Mission Portal. The Mission Portal is a graphical user interface that allows you to verify the actual state of all your Hosts, thus ensuring that your promises are being executed. -* Try out the Tutorials. Links to three tutorials give you a head start on learning CFEngine. +- Install CFEngine Enterprise onto a Policy Server and onto Hosts. A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. Hosts are clients that retrieve and execute promises. +- Bootstrap the policy server to itself and then bootstrap each of the Hosts to the Policy Server. Bootstrapping establishes a trust relationship between the Policy Server and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. Bootstrapping completes the installation process. +- Log in to the Mission Portal. The Mission Portal is a graphical user interface that allows you to verify the actual state of all your Hosts, thus ensuring that your promises are being executed. +- Try out the Tutorials. Links to three tutorials give you a head start on learning CFEngine. ### Step 1. Download and install Enterprise on a policy server @@ -133,9 +135,9 @@ This script installs the latest CFEngine Enterprise Policy Server on your server ### Step 2. Bootstrap the policy server -* The Policy Server must be bootstrapped to itself. Find the IP address of your Policy Server: - `$ ifconfig`. -* Run the bootstrap command: `sudo /var/cfengine/bin/cf-agent --bootstrap ` +- The Policy Server must be bootstrapped to itself. Find the IP address of your Policy Server: + `$ ifconfig`. +- Run the bootstrap command: `sudo /var/cfengine/bin/cf-agent --bootstrap ` Example: `$ sudo /var/cfengine/bin/cf-agent --bootstrap 172.31.3.25` @@ -143,16 +145,16 @@ This script installs the latest CFEngine Enterprise Policy Server on your server Upon successful completion, a confirmation message appears: "Bootstrap to '172.31.3.25' completed successfully!" -* Type the following to check which version of CFEngine your are running: +- Type the following to check which version of CFEngine your are running: - `/var/cfengine/bin/cf-promises --version` + `/var/cfengine/bin/cf-promises --version` -* The Policy Server is now installed. +- The Policy Server is now installed. ### Step 3. Install Enterprise on host (client) -* Ensure you are logged into the host machine setup earlier. -* Install CFEngine client version using the following: +- Ensure you are logged into the host machine setup earlier. +- Install CFEngine client version using the following: ```command wget https://s3.amazonaws.com/cfengine.packages/quick-install-cfengine-enterprise.sh && sudo bash ./quick-install-cfengine-enterprise.sh agent @@ -168,31 +170,31 @@ Note: You can install CFEngine Enterprise on up to 25 hosts using the script abo ### Step 4. Bootstrap the host to the policy server -* All hosts must be bootstrapped to the Policy Server in order to establish a connection between the `Host` and the `Policy Server`. -* Run the same commands that you ran in Step 2, `$ sudo /var/cfengine/bin/cfagent bootstrap `. +- All hosts must be bootstrapped to the Policy Server in order to establish a connection between the `Host` and the `Policy Server`. +- Run the same commands that you ran in Step 2, `$ sudo /var/cfengine/bin/cfagent bootstrap `. Example: `$ sudo /var/cfengine/bin/cfagent bootstrap 172.31.3.25` -* The installation process is complete and CFEngine Enterprise is up and running on your system. +- The installation process is complete and CFEngine Enterprise is up and running on your system. ### Step 5. Log in to the Mission Portal -* The Mission Portal is immediately accessible. Connect to the Policy Server through your web browser at: http:// (Note: The External IP address is available in the AWS console). -* The default username for the Mission Portal is `admin`, and the password is also `admin`. -* The Mission Portal runs TCP port 80 by default. [Configure mission portal to use HTTPS instead of HTTP](https://cfengine.zendesk.com/entries/25005193-Configure-Mission-Portal-to-use-HTTPS-instead-of-HTTP). -* During the initial setup, the Host(s) might take a few minutes to show up in the Mission Portal. Refresh the web page and login again if necessary. +- The Mission Portal is immediately accessible. Connect to the Policy Server through your web browser at: http:// (Note: The External IP address is available in the AWS console). +- The default username for the Mission Portal is `admin`, and the password is also `admin`. +- The Mission Portal runs TCP port 80 by default. [Configure mission portal to use HTTPS instead of HTTP](https://cfengine.zendesk.com/entries/25005193-Configure-Mission-Portal-to-use-HTTPS-instead-of-HTTP). +- During the initial setup, the Host(s) might take a few minutes to show up in the Mission Portal. Refresh the web page and login again if necessary. ## What next? ### Tutorials -* [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] +- [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] -* [Distributing files from a central location.][Distributing files from a central location] +- [Distributing files from a central location.][Distributing files from a central location] Whereas the first tutorial in this list teaches you how to deploy business policy through the Mission Portal, this advanced, command-line tutorial shows you how to distribute policy files from the Policy Server to all pertinent Hosts. ### Recommended reading -* [Tutorials and Examples][Examples and tutorials] +- [Tutorials and Examples][Examples and tutorials] diff --git a/content/getting-started/installation/general-installation/installation-enterprise-free.markdown b/content/getting-started/installation/general-installation/installation-enterprise-free.markdown index 014ef87b0..7be40b317 100644 --- a/content/getting-started/installation/general-installation/installation-enterprise-free.markdown +++ b/content/getting-started/installation/general-installation/installation-enterprise-free.markdown @@ -9,28 +9,28 @@ version of CFEngine Enterprise, but the number of Hosts (clients) is limited to **Note the following requirements:** -* To install this version of CFEngine Enterprise, your machine must be running a recent version of Linux. -This installation script has been tested on RHEL 5 and 6, SLES 11, CentOS 5 and 6, and Debian 6 and 7. -* You need a minimum of 2 GB of available memory and a modern 64 bit processor. -* Plan for approximately 100MB of disk space per host. You should provide an -extra 2G to 4G of disk space if you plan to bootstrap more hosts later. -* You need a least two VMs/servers, one for the Policy Server and one for a Host (client). They must be on the same network. -* The Policy Server needs to run on a dedicated OS with a vanilla installation (i.e. it only has repositories and packages officially -supported by the OS vendor) +- To install this version of CFEngine Enterprise, your machine must be running a recent version of Linux. + This installation script has been tested on RHEL 5 and 6, SLES 11, CentOS 5 and 6, and Debian 6 and 7. +- You need a minimum of 2 GB of available memory and a modern 64 bit processor. +- Plan for approximately 100MB of disk space per host. You should provide an + extra 2G to 4G of disk space if you plan to bootstrap more hosts later. +- You need a least two VMs/servers, one for the Policy Server and one for a Host (client). They must be on the same network. +- The Policy Server needs to run on a dedicated OS with a vanilla installation (i.e. it only has repositories and packages officially + supported by the OS vendor) ## Installation Overview During the course of the instructions outlined in this guide, you will perform the following tasks: -* **Install CFEngine Enterprise onto a Policy Server and onto Hosts.** -A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. -Hosts are clients that retrieve and execute promises. -* **Bootstrap the policy server to itself and then bootstrap each of the Hosts to the Policy Server.** Bootstrapping establishes a trust relationship between the Policy Server -and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. -Bootstrapping completes the installation process. -* **Log in to the Mission Portal.** The Mission Portal is a graphical user interface that allows you to verify the -the actual state of all your Hosts, thus ensuring that your promises are being executed. -* **Try out the Tutorials.** Links to three tutorials give you a head start on learning CFEngine. +- **Install CFEngine Enterprise onto a Policy Server and onto Hosts.** + A Policy Server (hub) is a CFEngine instance that contains promises (business policy) that get deployed to Hosts. + Hosts are clients that retrieve and execute promises. +- **Bootstrap the policy server to itself and then bootstrap each of the Hosts to the Policy Server.** Bootstrapping establishes a trust relationship between the Policy Server + and all Hosts. Thus, business policy that you create in the Policy Server can be deployed to Hosts throughout your company. + Bootstrapping completes the installation process. +- **Log in to the Mission Portal.** The Mission Portal is a graphical user interface that allows you to verify the + the actual state of all your Hosts, thus ensuring that your promises are being executed. +- **Try out the Tutorials.** Links to three tutorials give you a head start on learning CFEngine. ## 1. Download and install Enterprise on a policy server @@ -106,20 +106,20 @@ to configure the Mission Portal to use HTTPS instead of HTTP.) During the initia and login again if necessary. Note: If you are running Enterprise with Vagrant, you must add the -correct port: http://localhost: in your browser. The is the port-forwarder +correct port: http://localhost: in your browser. The is the port-forwarder number you use in your **Vagrantfile** (e.g. policyserver.vm.network "forwarded_port", guest: 80, host: 8080; the port will be 8080).
## Tutorials -* [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] +- [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] -* [Distributing files from a central location.][Distributing files from a central location] +- [Distributing files from a central location.][Distributing files from a central location] Whereas the first tutorial in this list teaches you how to deploy business policy through the Mission Portal, this advanced, command-line tutorial shows you how to distribute policy files from the Policy Server to all pertinent Hosts. ## Recommended reading -* [Tutorials and Examples][Examples and tutorials] +- [Tutorials and Examples][Examples and tutorials] diff --git a/content/getting-started/installation/general-installation/installation-enterprise-vagrant.markdown b/content/getting-started/installation/general-installation/installation-enterprise-vagrant.markdown index f6194ef79..eee4328f9 100644 --- a/content/getting-started/installation/general-installation/installation-enterprise-vagrant.markdown +++ b/content/getting-started/installation/general-installation/installation-enterprise-vagrant.markdown @@ -16,9 +16,10 @@ your Internet connection and disk speed). Upon completion, you are ready to start working with CFEngine. ## Requirements -* 2G disk space -* 3G memory -* CPU with VT extensions capable of running 64bit guests + +- 2G disk space +- 3G memory +- CPU with VT extensions capable of running 64bit guests Note: VirtualBox requires that your computer support hardware virtualization in order to make use of the virtual machines mentioned above. @@ -36,7 +37,7 @@ different approach][General installation#More detailed installation guides]. 3. Start the CFEngine Enterprise Vagrant Environment 4. Log in to the Mission Portal 5. Stop CFEngine Enterprise -5. Uninstall +6. Uninstall ## Install Vagrant @@ -71,17 +72,17 @@ vagrant up Vagrant performs the following processes: -* Downloads the basebox for both the hub and the client (if it has +- Downloads the basebox for both the hub and the client (if it has not already been cached by vagrant. -* Provisions, installs and bootstraps the hub -* Provisions, installs and bootstraps clients +- Provisions, installs and bootstraps the hub +- Provisions, installs and bootstraps clients The basebox is ~500MB. Note: If you want to use more hosts in this environment, you can - edit the **Vagrantfile** text file in the directory that you have just created. - Change the line that says "hosts = 1" to the number of hosts that you want in - the setup. The maximum supported in this evaluation version of CFEngine is 25. +edit the **Vagrantfile** text file in the directory that you have just created. +Change the line that says "hosts = 1" to the number of hosts that you want in +the setup. The maximum supported in this evaluation version of CFEngine is 25. ## Log in to the Mission Portal @@ -98,6 +99,7 @@ password: admin Portal. That's all there is to it, the install is complete! Move on and explore the environment. + ## Exploring the environment ### Accessing VMs diff --git a/content/getting-started/installation/general-installation/installation-enterprise.markdown b/content/getting-started/installation/general-installation/installation-enterprise.markdown index e98050a84..988dd318b 100644 --- a/content/getting-started/installation/general-installation/installation-enterprise.markdown +++ b/content/getting-started/installation/general-installation/installation-enterprise.markdown @@ -45,11 +45,11 @@ promise executions) by adjusting `def.max_client_history_size`. **Network** -* Verify that the machine's network connection is working and that +- Verify that the machine's network connection is working and that port 5308 (used by CFEngine) is open for both incoming and outgoing connections. -* If a firewall is active on your operating system, adapt it to it to +- If a firewall is active on your operating system, adapt it to it to allow for communication on port 5308 or disable it. CFEngine bundles all critical dependencies into the package; therefore, @@ -59,13 +59,13 @@ additional software is not required. CFEngine Enterprise has [Virtual I/O Server (VIOS) Recognized status](http://www.ibm.com/partnerworld/gsd/solutiondetails.do?solution=48493) -from IBM. This means that CFEngine Enterprise has been technically +from IBM. This means that CFEngine Enterprise has been technically verified by IBM to be installed in and manage VIOS environments. During testing, CFEngine Enterprise was seen to use up to 2% of the VIOS CPU during `cf-agent` runs with the default CFEngine policy. The resource utilization may vary depending on the policy CFEngine is -running. The VIOS should be configured with Shared Processors in +running. The VIOS should be configured with Shared Processors in Uncapped mode. ## Policy server requirements @@ -73,14 +73,14 @@ Uncapped mode. Please note that the resource requirements below are meant as minimum guidelines and have been obtained with synthetic testing, and it is always better to leave some headroom if intermittent bottlenecks -should occur. The key drivers for the vertical scalability of the +should occur. The key drivers for the vertical scalability of the Policy Servers are 1) the number of agents bootstrapped and 2) the size and complexity of the CFEngine policy. ### cfapache and cfpostgres users The CFEngine Server requires two users: **cfapache** and -**cfpostgres**. If these users do not exist during installation of +**cfpostgres**. If these users do not exist during installation of the server package, they will be created, so if there are constraints on user creation, please ensure that these users exists prior to installation. @@ -102,7 +102,7 @@ requirements when doing this. ### CPU A modern 64-bit processor with 12 or more cores for handling up to -5000 bootstrapped agents. This number is also linear with respect to +5000 bootstrapped agents. This number is also linear with respect to the number of bootstrapped agents (so 6 cores would suffice for 2500 agents). @@ -144,8 +144,8 @@ If you do not have separate partitions for `$(sys.workdir)` and 1500 IOPS and 10.5 MB/s). **Note** Your storage IOPS specification may be given in 4KiB block - size, in which case you would need to divide it by 4 to get the - corresponding 16KiB *theoretical maximum*. +size, in which case you would need to divide it by 4 to get the +corresponding 16KiB _theoretical maximum_. ### Network @@ -194,24 +194,24 @@ CFEngine Enterprise is provided in two packages; one is for the Policy Server (hub) and the other is for each Host (client). **Log in as root** and then follow these steps to install CFEngine - Enterprise: +Enterprise: 1. On the designated Policy Server, install the `cfengine-nova-hub` package: - ```console - [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm - [Debian/Ubuntu] # apt -y install /path/to/.deb - ``` + ```console + [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm + [Debian/Ubuntu] # apt -y install /path/to/.deb + ``` 2. On each Host, install the `cfengine-nova` package: - ```console - [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm - [Debian/Ubuntu] # apt -y install /path/to/.deb - [Solaris] # pkgadd -d .pkg all - [AIX] # installp -a -d .bff cfengine.cfengine-nova - [HP-UX] # swinstall -s .depot cfengine-nova - ``` + ```console + [RedHat/CentOS/SUSE] # yum -y install /path/to/.rpm + [Debian/Ubuntu] # apt -y install /path/to/.deb + [Solaris] # pkgadd -d .pkg all + [AIX] # installp -a -d .bff cfengine.cfengine-nova + [HP-UX] # swinstall -s .depot cfengine-nova + ``` Note: Install actions logged to `/var/logs/cfengine-install.log`. @@ -262,6 +262,6 @@ through your web browser at http://``. Learn more about CFEngine by using the following resources: -* Tutorial: [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] +- Tutorial: [Tutorial for running examples][Examples and tutorials#Tutorial for running examples] -* [Tutorials and Examples][Examples and tutorials] +- [Tutorials and Examples][Examples and tutorials] diff --git a/content/getting-started/installation/installation-overview.markdown b/content/getting-started/installation/installation-overview.markdown index e69dba83b..796a7d98c 100644 --- a/content/getting-started/installation/installation-overview.markdown +++ b/content/getting-started/installation/installation-overview.markdown @@ -18,11 +18,11 @@ See also: [Pre-installation checklist][Pre-installation checklist], [Supported p Additional options for configuring CFEngine policy are as follows: -* [Controlling frequency] -Learn how to control frequency settings for verifying CFEngine policy. +- [Controlling frequency] + Learn how to control frequency settings for verifying CFEngine policy. -* [Version control] -Learn how to put your CFEngine policies under version control. +- [Version control] + Learn how to put your CFEngine policies under version control. -* [Masterfiles Policy Framework] -Learn what options are available out of the box in CFEngine to configure its masterfiles operation. +- [Masterfiles Policy Framework] + Learn what options are available out of the box in CFEngine to configure its masterfiles operation. diff --git a/content/getting-started/installation/local-virtual-machine.markdown b/content/getting-started/installation/local-virtual-machine.markdown index c614c4295..7b399a5f8 100644 --- a/content/getting-started/installation/local-virtual-machine.markdown +++ b/content/getting-started/installation/local-virtual-machine.markdown @@ -18,8 +18,8 @@ There is a video version of this tutorial available on YouTube: Install Vagrant and VirtualBox from their respective websites: -* [Vagrant](https://www.vagrantup.com/downloads) -* [VirtualBox](https://www.virtualbox.org/) +- [Vagrant](https://www.vagrantup.com/downloads) +- [VirtualBox](https://www.virtualbox.org/) VirtualBox is used for virtualization, and vagrant is a nice way of interacting with the VirtualBox software, through the `vagrant` Command Line Interface (CLI), and in a `Vagrantfile`. @@ -97,10 +97,10 @@ end The `Vagrantfile` above does some important things: -* Defines a Ubuntu 20.04 Virtual machine called `hub`, with hostname `hub` -* Sets its IP address to be `192.168.56.2` -* Sets how much memory and CPU cores we want the VM to have -* Copies the `id_rsa.pub` public key into the host when it starts, so we can use `ssh` +- Defines a Ubuntu 20.04 Virtual machine called `hub`, with hostname `hub` +- Sets its IP address to be `192.168.56.2` +- Sets how much memory and CPU cores we want the VM to have +- Copies the `id_rsa.pub` public key into the host when it starts, so we can use `ssh` **Note:** The machine will be called `hub` in `vagrant`, `cf-remote` and in Mission Portal (based on hostname), but this is just because we were consistent when naming it in all 3 places. These 3 names do not have to match, but it is easier to remember diff --git a/content/getting-started/installation/pre-installation-checklist/_index.markdown b/content/getting-started/installation/pre-installation-checklist/_index.markdown index 0df50b90c..2d140a7bd 100644 --- a/content/getting-started/installation/pre-installation-checklist/_index.markdown +++ b/content/getting-started/installation/pre-installation-checklist/_index.markdown @@ -15,9 +15,9 @@ for [Supported platforms and versions][Supported platforms and versions] operati ## Required knowledge -* Linux -* SSH -* bash -* command line text editing (e.g. vi/vim, Emacs) +- Linux +- SSH +- bash +- command line text editing (e.g. vi/vim, Emacs) See also: [Quick-Start Guide to Using vi][Quick-Start Guide to Using vi], [Quick-Start Guide to Using PuTTY][Quick-Start Guide to Using PuTTY] diff --git a/content/getting-started/installation/pre-installation-checklist/putty-quick-start-guide.markdown b/content/getting-started/installation/pre-installation-checklist/putty-quick-start-guide.markdown index 773778739..27287777f 100644 --- a/content/getting-started/installation/pre-installation-checklist/putty-quick-start-guide.markdown +++ b/content/getting-started/installation/pre-installation-checklist/putty-quick-start-guide.markdown @@ -4,8 +4,8 @@ layout: default sorting: 2 --- -* [Using PuTTY in simple steps][Quick-Start Guide to Using PuTTY#Using PuTTY in simple steps] -* [Accessing AWS virtual machines via SSH on Windows using PuTTY and PuTTYgen][Quick-Start Guide to Using PuTTY#Accessing AWS virtual machines via SSH on Windows using PuTTY and PuTTYgen] +- [Using PuTTY in simple steps][Quick-Start Guide to Using PuTTY#Using PuTTY in simple steps] +- [Accessing AWS virtual machines via SSH on Windows using PuTTY and PuTTYgen][Quick-Start Guide to Using PuTTY#Accessing AWS virtual machines via SSH on Windows using PuTTY and PuTTYgen] ## Using PuTTY in simple steps @@ -17,7 +17,7 @@ a client computer to a remote Linux/Unix server. Many of the tutorials to follow will refer to using PuTTY, which is a popular SSH client for Windows workstations. The important thing about PuTTY is that it is a _secure_ way to connect a client to a server, -using the SSH network protocol. It has a powerful and easy-to-use graphical user interface (GUI) and is used +using the SSH network protocol. It has a powerful and easy-to-use graphical user interface (GUI) and is used to run a remote session over a network. What is SSH? It is short-form for "Secure Shell," which means it creates a _secure channel_ over an @@ -31,13 +31,13 @@ Since CFEngine is a client-server enterprise software system, it is essential to securely. This is true whether the CFEngine system is run on a cloud platform, like Amazon Web Services and many others-or on a private network. -That is where PuTTY comes into the picture, since it uses SSH protocol for connecting a client to a server. +That is where PuTTY comes into the picture, since it uses SSH protocol for connecting a client to a server. The PuTTY software consists of two separate programs PuTTY and PuTTYgen: They can be downloaded at http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTYgen is used to generate the encryption key pair while PuTTY, a command-line interface, - is used to securely access the CFEngine server, or _hub_, from a remote client machine, which is called +is used to securely access the CFEngine server, or _hub_, from a remote client machine, which is called a _host_ in CFEngine terminology. PuTTYgen is used only when setting up a new client machine on the CFEngine hub. The CFEngine _hub_ will already @@ -65,7 +65,7 @@ a. Click _Load_. The following _Load private key_ window will pop up: ![The PuTTYgen "Load private key" pop-up window](puttygen-load-private-key-window.png) -b. In the Load private key window select All Files (*.*) in the drop down menu next to the +b. In the Load private key window select All Files (_._) in the drop down menu next to the File name input box. c. Navigate to the location on disk where the _public-key_ file was downloaded in earlier steps, in this @@ -85,77 +85,79 @@ g. Now close PuTTYgen. ### Get PuTTY and PuTTYgen -* To get PuTTY and PuTTYgen, first go to -http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html and either: - * Download and install using the PuTTY binaries installer - * Or, download PuTTY and PuTTYgen individually +- To get PuTTY and PuTTYgen, first go to + http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html and either: +- Download and install using the PuTTY binaries installer +- Or, download PuTTY and PuTTYgen individually ### Prepare private key using PuTTYgen -* After the binaries have been downloaded and/or installed either: - * Double click `puttygen.exe` from the download location, if downloaded directly. - * Or, if the PuTTY installer was used above, one of either: - * Press the `Windows` key + `R` key and then type `puttygen` in the field named `Open`. Then press the `Enter` key or click `OK`. - * Alternatively, double click puttygen.exe under `C:\Program Files (x86)\PuTTY` (when using Windows 64 bit) or `C:\Program Files\PuTTY` (when using Windows 32 bit). + +- After the binaries have been downloaded and/or installed either: +- Double click `puttygen.exe` from the download location, if downloaded directly. +- Or, if the PuTTY installer was used above, one of either: +- Press the `Windows` key + `R` key and then type `puttygen` in the field named `Open`. Then press the `Enter` key or click `OK`. +- Alternatively, double click puttygen.exe under `C:\Program Files (x86)\PuTTY` (when using Windows 64 bit) or `C:\Program Files\PuTTY` (when using Windows 32 bit). ![The Puttygen Interface](Installing-CFE-on-AWS-1.png) The Puttygen Interface. You will load the .pem file that you created in AWS. -* On the PuTTYgen interface click the load button. -* In the Load private key window select All Files (*.*) in the drop down menu next to the -File name input box. -* Navigate to the location on disk where the .pem file was downloaded in earlier steps. -* When the key has been loaded click the Save private key button. -* When prompted with a warning about saving without a passphrase, click yes. +- On the PuTTYgen interface click the load button. +- In the Load private key window select All Files (_._) in the drop down menu next to the + File name input box. +- Navigate to the location on disk where the .pem file was downloaded in earlier steps. +- When the key has been loaded click the Save private key button. +- When prompted with a warning about saving without a passphrase, click yes. ![The Puttygen popup window](Installing-CFE-on-AWS-2.png) The Puttygen popup window. Click `Yes`, to proceed without a passphrase. You can also protect your private key with a passphrase that you enter into `Key Passprhase` and `Confirm Key Passphrase`. -* Finally, navigate to a good location on disk to save the key file, enter a name for the private key, ensure PuTTY Private Key Files (*.ppk) type is selected, and then click the Save button. -* You can now close the Puttygen application. You will call up the .ppk file when you configure the virtual machines using PuTTY. +- Finally, navigate to a good location on disk to save the key file, enter a name for the private key, ensure PuTTY Private Key Files (\*.ppk) type is selected, and then click the Save button. +- You can now close the Puttygen application. You will call up the .ppk file when you configure the virtual machines using PuTTY. ### Configure PuTTY -* Before configuring PuTTY, go back to your AWS Console, then navigate to INSTANCES > Instances. -* Make a note of the 2 different Public DNS entries for the virtual machines that were setup earlier (e.g. ec2xxxxxxxxxxxx.uswest1.compute.amazonaws.com, where the x's represent numbers). -* Launch PuTTY by either: - * Double clicking `putty.exe` from the download location, if downloaded directly. - * Or, if the PuTTY installer was used above, one of either: - * Press the `Windows` key + `R` key and then type `putty` in the field named `Open`. Then press the `Enter` key or click `OK`. - * Alternatively, double click `putty.exe` under `C:\Program Files (x86)\PuTTY` (when using Windows 64 bit) or `C:\Program Files\PuTTY` (when using Windows 32 bit). - * On the PuTTY interface, select `Category > Session` on the left side navigation tree: +- Before configuring PuTTY, go back to your AWS Console, then navigate to INSTANCES > Instances. +- Make a note of the 2 different Public DNS entries for the virtual machines that were setup earlier (e.g. ec2xxxxxxxxxxxx.uswest1.compute.amazonaws.com, where the x's represent numbers). +- Launch PuTTY by either: +- Double clicking `putty.exe` from the download location, if downloaded directly. +- Or, if the PuTTY installer was used above, one of either: +- Press the `Windows` key + `R` key and then type `putty` in the field named `Open`. Then press the `Enter` key or click `OK`. +- Alternatively, double click `putty.exe` under `C:\Program Files (x86)\PuTTY` (when using Windows 64 bit) or `C:\Program Files\PuTTY` (when using Windows 32 bit). +- On the PuTTY interface, select `Category > Session` on the left side navigation tree: ![The Puttygen Interface](Installing-CFE-on-AWS-3.png) The Putty interface, with `Session` selected on the left-side navigation tree. -* Now, we will configure the Putty application, which we will use to set up the two AWS virtual machines. - * The first step is to create a Host Name for the first VM. - * The Host Name consists mainly of the public DNS entry that was created for one of the two virtual machines in AWS. But the DNS is preceded by a user name, `ec2-user`, followed by the `@` symbol, which is then followed by the DNS entry. +- Now, we will configure the Putty application, which we will use to set up the two AWS virtual machines. +- The first step is to create a Host Name for the first VM. +- The Host Name consists mainly of the public DNS entry that was created for one of the two virtual machines in AWS. But the DNS is preceded by a user name, `ec2-user`, followed by the `@` symbol, which is then followed by the DNS entry. ![Setting up the PuTTY configuration](Installing-CFE-on-AWS-4.png) Setting up the PuTTY configuration with the Host Name, and a Saved Sessions Name. - * Port should be set to `22`. - * Connection type should be set to `SSH`. - * `Saved Sessions` can be any label. +- Port should be set to `22`. +- Connection type should be set to `SSH`. +- `Saved Sessions` can be any label. Once we have entered our Host Name and our Saved Sessions name, we take the following steps: - * Select `Connection > SSH > Auth` on the left side navigation tree. - * Click the `Browse` button to select the `Private key for authentication`. - * In the `Select private key file` window, navigate to the .ppk private key file created earlier, and double-click on it to enter it into PuTTY. Your PuTTY screen should look like this: + +- Select `Connection > SSH > Auth` on the left side navigation tree. +- Click the `Browse` button to select the `Private key for authentication`. +- In the `Select private key file` window, navigate to the .ppk private key file created earlier, and double-click on it to enter it into PuTTY. Your PuTTY screen should look like this: ![Setting up the PuTTY configuration](Installing-CFE-on-AWS-5.png) Note that `Auth` has been selected on left-side tree, in order to bring up this screen. - * Now we go back and select `Category > Session` on the left side navigation tree and then press the `Save` button. - * Repeat the steps for the second virtual machine, starting from setting the Host Name through pressing the Save button (as described above). Your PuTTY screen should show the two saved virtual machines, which are here named `Examples 1 and 2.` - * Note: It may be necessary to redo the steps from selecting `Connection > SSH > Auth` through selecting the .ppk private key file. In other words, when configuring the connection the private key file may not be persistently saved. - * Wait a moment, and select `Yes` if prompted. - * This prompt will generally only be necessary when trying to login for the very first time. +- Now we go back and select `Category > Session` on the left side navigation tree and then press the `Save` button. +- Repeat the steps for the second virtual machine, starting from setting the Host Name through pressing the Save button (as described above). Your PuTTY screen should show the two saved virtual machines, which are here named `Examples 1 and 2.` +- Note: It may be necessary to redo the steps from selecting `Connection > SSH > Auth` through selecting the .ppk private key file. In other words, when configuring the connection the private key file may not be persistently saved. +- Wait a moment, and select `Yes` if prompted. +- This prompt will generally only be necessary when trying to login for the very first time. ![The PuTTY interface with the two virtual machines saved](Installing-CFE-on-AWS-6.png) @@ -163,12 +165,12 @@ The PuTTY interface with the two virtual machines saved. We can now proceed to c ### Login to virtual machines using PuTTY -* If one of the two virtual machines is configured and its details loaded in the PuTTY interface, first select the machine, then click the Open button. This will close the above PuTTY interface and open a command-line window, from which we will setup CFEngine on each of the two machines. One machine will act as the Server and the other as the client, and they will each be set up with different software. -* Once the first virtual machine is logged into, right click the top of PuTTY's application window (e.g. the part of the window decoration displaying the virtual machine name). -* In the contextual menu that then shows click New Session. -* Select the second virtual machine entry in the Saved Sessions list. -* Click Load and then Open. -* Both virtual machines should now be accessed in two different PuTTY command-line windows. Below is an example of what the command-line window will look like. +- If one of the two virtual machines is configured and its details loaded in the PuTTY interface, first select the machine, then click the Open button. This will close the above PuTTY interface and open a command-line window, from which we will setup CFEngine on each of the two machines. One machine will act as the Server and the other as the client, and they will each be set up with different software. +- Once the first virtual machine is logged into, right click the top of PuTTY's application window (e.g. the part of the window decoration displaying the virtual machine name). +- In the contextual menu that then shows click New Session. +- Select the second virtual machine entry in the Saved Sessions list. +- Click Load and then Open. +- Both virtual machines should now be accessed in two different PuTTY command-line windows. Below is an example of what the command-line window will look like. ![The PuTTY command-line window](Installing-CFE-on-AWS-7.png) diff --git a/content/getting-started/installation/pre-installation-checklist/vi-quick-start-guide.markdown b/content/getting-started/installation/pre-installation-checklist/vi-quick-start-guide.markdown index 69e177d1b..6f4c2889f 100644 --- a/content/getting-started/installation/pre-installation-checklist/vi-quick-start-guide.markdown +++ b/content/getting-started/installation/pre-installation-checklist/vi-quick-start-guide.markdown @@ -27,7 +27,7 @@ Step 1. Inside the shell prompt, simply type "vi". This will allow the user to i Step 2. type "i" then press the "Enter" key. This takes the user to the insert mode, and allow typing in text or copying and pasting. -Step 3. Type some text-for example, the obligatory "Hello World" (which will be the subject of a later tutorial). +Step 3. Type some text-for example, the obligatory "Hello World" (which will be the subject of a later tutorial). Now press "Enter" to go to the next line and type "My name is Gary, and it's nice to meet you." The output will look like this: diff --git a/content/getting-started/installation/secure-bootstrap.markdown b/content/getting-started/installation/secure-bootstrap.markdown index e02ad92e9..d860d9504 100644 --- a/content/getting-started/installation/secure-bootstrap.markdown +++ b/content/getting-started/installation/secure-bootstrap.markdown @@ -23,21 +23,21 @@ However, this is in the default configuration, and there are several limitations In the default configuration, the policy server (`cf-serverd`) on the hub machine trusts incoming connections from the same `/16` subnet. This means that: -* Bootstrapping new clients will work as long as the 2 first numbers in the IP address are identical ([IPv4 dot decimal representation](https://en.wikipedia.org/wiki/Dot-decimal_notation)) . +- Bootstrapping new clients will work as long as the 2 first numbers in the IP address are identical ([IPv4 dot decimal representation](https://en.wikipedia.org/wiki/Dot-decimal_notation)) . The hub and client mutually accept each other's keys, automatically. -* This applies to _all_ IP addresses within that range, not just the 1 IP address belonging to the client you are currently bootstrapping. -* The hub will keep accepting new clients from those IP addresses until you change the configuration. -* If you try to bootstrap a client where those 2 numbers in the IP address do not match the hub, it will fail. +- This applies to _all_ IP addresses within that range, not just the 1 IP address belonging to the client you are currently bootstrapping. +- The hub will keep accepting new clients from those IP addresses until you change the configuration. +- If you try to bootstrap a client where those 2 numbers in the IP address do not match the hub, it will fail. This situation, where the client and hub automatically transfer and trust each other's keys is called _automatic trust_ or _automatic bootstrap_. -When using automatic trust, it is presumed that during this first key exchange, *the network is trusted*, and no attacker will hijack the connection. +When using automatic trust, it is presumed that during this first key exchange, _the network is trusted_, and no attacker will hijack the connection. Below we will show ways to change the configuration and bootstrap your clients in more secure ways. The goal here is to illustrate the different approaches, explaining what is needed and the implications of each. In the end, you will not be running these commands manually, but rather putting them into a provisioning system. ## Allowing only specific IP addresses / subnets -In order to specify and limit which hosts (IP addresses) are considered trusted and allowed to connect and fetch policy files, you can put the trusted IP addresses and subnets into the ```acl``` variable: +In order to specify and limit which hosts (IP addresses) are considered trusted and allowed to connect and fetch policy files, you can put the trusted IP addresses and subnets into the `acl` variable: ```json {file="/var/cfengine/masterfiles/def.json"} { @@ -145,9 +145,9 @@ BOOTSTRAP_IP="192.0.2.42" HUB_SSH="ubuntu@192.0.2.42" CLIENT_SSH="ubuntu@198.51. Edit the 3 variables according to your situation, they represent: -* `BOOTSTRAP_IP` - The IP address of the hub, which you want `cf-agent` on the client to bootstrap to (connect to). -* `HUB_SSH` - The username / IP combination you would use to connect to the hub with SSH. -* `CLIENT_SSH` - The username / IP combination you would use to connect to the hub with SSH. +- `BOOTSTRAP_IP` - The IP address of the hub, which you want `cf-agent` on the client to bootstrap to (connect to). +- `HUB_SSH` - The username / IP combination you would use to connect to the hub with SSH. +- `CLIENT_SSH` - The username / IP combination you would use to connect to the hub with SSH. ### Trusting the client's key on the hub diff --git a/content/getting-started/installation/upgrading.markdown b/content/getting-started/installation/upgrading.markdown index aeeec0ccb..e7533a925 100644 --- a/content/getting-started/installation/upgrading.markdown +++ b/content/getting-started/installation/upgrading.markdown @@ -19,7 +19,7 @@ In short, the steps are: - Upgrades are supported from any [currently supported version][supported versions]. -- Clients should not run *newer* versions of binaries than the hub. While it may +- Clients should not run _newer_ versions of binaries than the hub. While it may work in many cases, Enterprise reporting does not currently guarantee forward compatibility. For example, a host running 3.15.0 will not be able to report to a hub running 3.12.3. @@ -148,7 +148,7 @@ empty before performing an Enterprise Hub binary upgrade. root@hub:~# dpkg --install cfengine-nova-hub_{{site.cfengine.branch}}.{{site.cfengine.latest_patch_release}}-{{site.cfengine.latest_package_build}}_amd64-deb7.deb ``` - *Community does not have a hub specific package.* + _Community does not have a hub specific package._ 3. Check `/var/log/CFEngine-Install.log` for errors. @@ -194,7 +194,6 @@ empty before performing an Enterprise Hub binary upgrade. automatically turns off on hosts after they reach the target version. 3. Verify that the selected hosts are upgrading successfully. - - Mission Portal [Inventory reporting interface][Reporting UI#Inventory management] ![Inventory management](Reports-Inventory-1.png) diff --git a/content/getting-started/modules-from-cfengine-build.markdown b/content/getting-started/modules-from-cfengine-build.markdown index f885db369..262e432b9 100644 --- a/content/getting-started/modules-from-cfengine-build.markdown +++ b/content/getting-started/modules-from-cfengine-build.markdown @@ -146,9 +146,9 @@ By clicking on _Reports_ and _Compliance_ we can see the report we added, _OS is Now that you've successfully added modules and seen the results in Mission Portal, you're ready to look for more modules, or explore Mission Portal further. Here are some examples of modules you might be interested in: -* [Inventory (reporting) data of who can use sudo on each host](https://build.cfengine.com/modules/inventory-sudoers/) -* [Scan and report on potentially vulnerable log4j installations](https://build.cfengine.com/modules/cve-2021-44228-log4j/) -* [Upgrade all packages with the system's package manager (apt, yum, etc.)](https://build.cfengine.com/modules/upgrade-all-packages/) +- [Inventory (reporting) data of who can use sudo on each host](https://build.cfengine.com/modules/inventory-sudoers/) +- [Scan and report on potentially vulnerable log4j installations](https://build.cfengine.com/modules/cve-2021-44228-log4j/) +- [Upgrade all packages with the system's package manager (apt, yum, etc.)](https://build.cfengine.com/modules/upgrade-all-packages/) To add more modules, just repeat the commands from steps 1-3. For example, add the `inventory-sudoers` module to your project: diff --git a/content/getting-started/writing-policy.markdown b/content/getting-started/writing-policy.markdown index 7c9677c0e..6c3002f69 100644 --- a/content/getting-started/writing-policy.markdown +++ b/content/getting-started/writing-policy.markdown @@ -124,9 +124,9 @@ Since it's the same every time, we won't mention it again and again. The promise type `vars` is used for storing data in a variable internally. This has several benefits: -* The data, such as a string, gets a short and descriptive name -* It can be defined in one place, and edited there without having to update multiple places -* Gives you more flexibiltiy for manipulating the data, with functions and intermediate variables +- The data, such as a string, gets a short and descriptive name +- It can be defined in one place, and edited there without having to update multiple places +- Gives you more flexibiltiy for manipulating the data, with functions and intermediate variables Here is a simple example: @@ -210,6 +210,6 @@ Next, we will look at implementing modules, such as the git promise type we used If you would like to learn more about policy writing, these are some good resources to look at: -* [Language concepts][Language concepts] -* [Promise types][Promise types] -* [Functions][Functions] +- [Language concepts][Language concepts] +- [Promise types][Promise types] +- [Functions][Functions] diff --git a/content/guide/_index.markdown b/content/guide/_index.markdown index a22fc4d7c..32e82183d 100644 --- a/content/guide/_index.markdown +++ b/content/guide/_index.markdown @@ -13,25 +13,25 @@ See also: [Overview][Overview] ## CFEngine features -* Defines the configuration of an entire IT system, including: Devices, Users, Applications, and Services. -* Helps maintain that system over time. -* Checks the system state at any given moment. -* Ensures compliance with a desired system state. -* Propagates real-time modifications or updates across the system. +- Defines the configuration of an entire IT system, including: Devices, Users, Applications, and Services. +- Helps maintain that system over time. +- Checks the system state at any given moment. +- Ensures compliance with a desired system state. +- Propagates real-time modifications or updates across the system. ## Choose a CFEngine version [CFEngine Enterprise](https://cfengine.com/product-overview/) is a licensed edition for enterprises that plan to use the tool in production environments. The Enterprise edition comes in several variants, including one that can be evaluated for free (up to 25 servers). -* [Get the Enterprise Edition][evaluate cfengine] +- [Get the Enterprise Edition][evaluate cfengine] CFEngine Community, a free GPL v3 open source edition. -* [Get the Community Edition][community download page] +- [Get the Community Edition][community download page] See also: -* [Supported platforms and versions][Supported platforms and versions] +- [Supported platforms and versions][Supported platforms and versions] ## Install it @@ -45,7 +45,7 @@ CFEngine up and running for various environments. Walk through the examples, tutorials and how to guides to get a better feel for the power and value of CFEngine: -* [Policy Examples and tutorials][Examples and tutorials] +- [Policy Examples and tutorials][Examples and tutorials] ## Learn more @@ -60,17 +60,17 @@ experts if you need more help. Contact us! ## CFEngine guide -* [Overview][] -* [Release notes][] -* [Installation][] - * [Pre-installation checklist] - * [General installation] - * [Upgrading] - * [Secure bootstrap] -* [Writing and serving policy][] - * [Language concepts][] - * [Promises available in CFEngine][] - * [Authoring policy tools & workflow][] -* [Reports][] -* [FAQ][] -* [External Resources][] +- [Overview][] +- [Release notes][] +- [Installation][] + - [Pre-installation checklist] + - [General installation] + - [Upgrading] + - [Secure bootstrap] +- [Writing and serving policy][] + - [Language concepts][] + - [Promises available in CFEngine][] + - [Authoring policy tools & workflow][] +- [Reports][] +- [FAQ][] +- [External Resources][] diff --git a/content/overview/_index.markdown b/content/overview/_index.markdown index 13c2f6de6..7d76d11d4 100644 --- a/content/overview/_index.markdown +++ b/content/overview/_index.markdown @@ -4,13 +4,13 @@ title: Overview sorting: 10 --- -CFEngine is a distributed system for managing and monitoring computers across an IT network. Machines on the network that have CFEngine installed, and have registered themselves with a policy server (see [Installation][Installation]), will each be running a set of CFEngine component applications that manage and interpret textual files called policies. Policy files themselves contain sets of instructions to ensure machines on the network are in full compliance with a defined state. At the atomic level are sets, or *bundles*, of what are known in the CFEngine world as [Promises][Promises]. *Promises* are at the heart of Promise Theory, which is in turn what CFEngine is all about. +CFEngine is a distributed system for managing and monitoring computers across an IT network. Machines on the network that have CFEngine installed, and have registered themselves with a policy server (see [Installation][Installation]), will each be running a set of CFEngine component applications that manage and interpret textual files called policies. Policy files themselves contain sets of instructions to ensure machines on the network are in full compliance with a defined state. At the atomic level are sets, or _bundles_, of what are known in the CFEngine world as [Promises][Promises]. _Promises_ are at the heart of Promise Theory, which is in turn what CFEngine is all about. ## Policy language and compliance For many users, CFEngine is simply a configuration tool - i.e. software for deploying and patching systems according to a policy. Policy is described using promises. Every statement in CFEngine 3 is a promise to be kept at some time or location. More than this, however, CFEngine is not like other automation tools that "roll out" an image of some software once and hope for the best. Every promise that you make in CFEngine is continuously verified and maintained. It is not a one-off operation, but a self-repairing process should anything deviate from the policy. -CFEngine ensures that the actual state of a system is in compliance with the predefined model of desired state for the system. If it is not in compliance CFEngine will bring it into compliance. This is known as *convergence*. +CFEngine ensures that the actual state of a system is in compliance with the predefined model of desired state for the system. If it is not in compliance CFEngine will bring it into compliance. This is known as _convergence_. That model is represented by one or more policies that have been written using the declarative CFEngine policy language. The policy language has been designed with a vocabulary that is intuitive, yet at the same time can still support the design of highly complex IT systems. @@ -45,16 +45,16 @@ All CFEngine software components exist in `/var/cfengine/bin`. ![Components overview](components-overview.png) -* [Daemons][Overview#Daemons] -* [Other Applications][Overview#Other component applications] +- [Daemons][Overview#Daemons] +- [Other Applications][Overview#Other component applications] ### Daemons All machines, whether they are policy servers or hosts, will have these three important daemons running at all times: -* [/var/cfengine/bin/cf-execd][Overview#cf-execd] -* [/var/cfengine/bin/cf-serverd][Overview#cf-serverd] -* [/var/cfengine/bin/cf-monitord][Overview#cf-monitord] +- [/var/cfengine/bin/cf-execd][Overview#cf-execd] +- [/var/cfengine/bin/cf-serverd][Overview#cf-serverd] +- [/var/cfengine/bin/cf-monitord][Overview#cf-monitord] #### cf-execd @@ -95,10 +95,10 @@ See also: [cf-monitord][cf-monitord] reference documentation. ### Other component applications -* [/var/cfengine/bin/cf-agent][Overview#cf-agent] -* [/var/cfengine/bin/cf-key][Overview#cf-key] -* [/var/cfengine/bin/cf-promises][Overview#cf-promises] -* [/var/cfengine/bin/cf-runagent][Overview#cf-runagent] +- [/var/cfengine/bin/cf-agent][Overview#cf-agent] +- [/var/cfengine/bin/cf-key][Overview#cf-key] +- [/var/cfengine/bin/cf-promises][Overview#cf-promises] +- [/var/cfengine/bin/cf-runagent][Overview#cf-runagent] #### cf-agent diff --git a/content/overview/client-server-communication.markdown b/content/overview/client-server-communication.markdown index f2b55f90c..4df5fde5c 100644 --- a/content/overview/client-server-communication.markdown +++ b/content/overview/client-server-communication.markdown @@ -12,11 +12,11 @@ containing `access` promises. The server can allow the network to access files or to execute CFEngine: -* The only contact [`cf-agent`][cf-agent] makes to the server is via remote copy +- The only contact [`cf-agent`][cf-agent] makes to the server is via remote copy requests. It does not and cannot grant any access to a system from the network. It is only able to request access to files on the remote server. -* [`cf-runagent`][cf-runagent] can be used to run `cf-agent` on a number +- [`cf-runagent`][cf-runagent] can be used to run `cf-agent` on a number of remote hosts. Unlike other approaches to automation, CFEngine does not rely on SSH key @@ -36,22 +36,22 @@ fault tolerant and opportunistic. In order to connect to the CFEngine server you need: -* **A public-private key pair**. It is automatically generated during package +- **A public-private key pair**. It is automatically generated during package installation or during bootstrap. To manually create a key pair, run `cf-key`. -* **Network connectivity** with an IPv4 or IPv6 address. -* **Permission to connect** to the server. +- **Network connectivity** with an IPv4 or IPv6 address. +- **Permission to connect** to the server. The [`server control`][cf-serverd#Control promises] body must grant access to your computer and public key by name or IP address, by listing it in the appropriate access lists (see below). -* **Mutual key trust**. +- **Mutual key trust**. Your public key must be trusted by the server, and you must trust the server's public key. The first part is established by having the [`trustkeysfrom`][cf-serverd#trustkeysfrom] setting open on the server for the first connection of the agent. It should be closed later to avoid trusting new agents. The second part is established by bootstrapping the agent to the hub, or by executing a `copy_from` files promise using `trustkey=>"true"`. -* **Permission to access something**. +- **Permission to access something**. Your host name or IP address must be mentioned in an `access` promise inside a server bundle, made by the file that you are trying to access. @@ -315,7 +315,7 @@ There is a simple checklist for curing this problem: 3. See the verbose log of the server for the exact error message, since the client always gets the "Unspecified server refusal" reply from the server. To run the server in verbose, kill cf-serverd on the policy hub and run: - $ cf-serverd -v + $ cf-serverd -v and then manually run `cf-agent` on the client. 4. In the unlikely case that you still get no indication of the denial, try increasing the agent run verbosity. `cf-agent -I` for info-level messages diff --git a/content/overview/directory-structure.markdown b/content/overview/directory-structure.markdown index 43a4a4a85..efae44aea 100644 --- a/content/overview/directory-structure.markdown +++ b/content/overview/directory-structure.markdown @@ -10,18 +10,18 @@ The CFEngine application is fully contained within the /var/cfengine directory t ### Agents -* `cf-agent`: Executes the promises.cf file; ensures that all promises are being kept -* `cf-key` -* `cf-promises`: Verifies CFEngine's configuration syntax -* `cf-runagent`: Contacts a remote system to run cf-agent +- `cf-agent`: Executes the promises.cf file; ensures that all promises are being kept +- `cf-key` +- `cf-promises`: Verifies CFEngine's configuration syntax +- `cf-runagent`: Contacts a remote system to run cf-agent ### Daemons -* `cf-execd`: Starts the cf-agent process at a specified time interval. -* `cf-monitord`: Collects system statistics -* `cf-serverd`: Provides network services; used to distribute policy and data files -* `runalerts.sh`: Updates Mission Portal status and activates alert actions (Enterprise only) -* `cf-hub`: Responsible for collecting reports from remote agents. (CFEngine Enterprise only) +- `cf-execd`: Starts the cf-agent process at a specified time interval. +- `cf-monitord`: Collects system statistics +- `cf-serverd`: Provides network services; used to distribute policy and data files +- `runalerts.sh`: Updates Mission Portal status and activates alert actions (Enterprise only) +- `cf-hub`: Responsible for collecting reports from remote agents. (CFEngine Enterprise only) See also: [CFEngine component applications and daemons][Overview#CFEngine component applications and daemons] @@ -64,11 +64,11 @@ should delete these files after a time to avoid a build up. State data such as current process identifiers of running processes, persistent classes and other cached data. -* `/var/cfengine/state/promise_execution.log`: In CFEngine Enterprise `cf-agent` writes promise execution results to this temporary file during execution. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. +- `/var/cfengine/state/promise_execution.log`: In CFEngine Enterprise `cf-agent` writes promise execution results to this temporary file during execution. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. -* `/var/cfengine/state/variable.cache.tmp`: In CFEngine Enterprise as `cf-agent` executes information about variables are stored in this file. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. +- `/var/cfengine/state/variable.cache.tmp`: In CFEngine Enterprise as `cf-agent` executes information about variables are stored in this file. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. -* `/var/cfengine/state/context.cache.tmp`: In CFEngine Enterprise as `cf-agent` executes, information about classes that are defined are stored in this file. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. +- `/var/cfengine/state/context.cache.tmp`: In CFEngine Enterprise as `cf-agent` executes, information about classes that are defined are stored in this file. When `cf-agent` exits this data is stored for use by the reporting subsystem and the file is purged. ### /var/cfengine/lastseen @@ -106,28 +106,28 @@ On hosts, CFEngine writes numerous logs and records to its private workspace. [CFEngine Enterprise](https://cfengine.com/product-overview/) provides solutions for centralization and network-wide reporting at an arbitrary scale. -* `cf3.[hostname].runlog` +- `cf3.[hostname].runlog` A time-stamped log of when each lock was released. This shows the last time each individual promise was verified. -* `cfagent.[hostname].log` +- `cfagent.[hostname].log` Although ambiguously named (for historical reasons) this log contains the current list of setuid/setgid programs observed on the system. CFEngine warns about new additions to this list. This log has been deprecated. -* `cf_notkept.log` +- `cf_notkept.log` In CFEngine Enterprise, a list of promises, with handles and comments, that were not kept. -* `cf_repair.log` +- `cf_repair.log` In CFEngine Enterprise, a list of promises, with handles and comments, that were repaired. -* `promise_summary.log` +- `promise_summary.log` A time-stamped log of the percentage fraction of promises kept after each run. @@ -160,7 +160,9 @@ The database of hash values used in CFEngine's change management functions. ### state/nova_agent_execution.lmdb + ### state/nova_track.lmdb + ### state/performance.lmdb A database of last, average and deviation times of jobs recorded by @@ -174,14 +176,14 @@ default. Other checks can be instrumented by setting a The CFEngine components keep their current process identifier number in _pid files_ in the work directory. -* `cf-execd.pid` -* `cf-hub.pid` -* `cf-monitord.pid` -* `cf-serverd.pid` +- `cf-execd.pid` +- `cf-hub.pid` +- `cf-monitord.pid` +- `cf-serverd.pid` ## Sockets in /var/cfengine -* `cf-hub-local` +- `cf-hub-local` ## Datafiles in /var/cfengine @@ -197,123 +199,123 @@ If an interface matches a regular expression in the file then various classes an **Classes:** -* `ipv4_` prefixed classes -* `mac_` prefixed classes +- `ipv4_` prefixed classes +- `mac_` prefixed classes **Variables:** -* `sys.ipv4_N[iface]` -* `sys.ip2iface` -* `sys.ipaddresses` -* `sys.interface_flags` -* `sys.inet` -* `sys.inet6` -* `sys.hardware_mac[iface]` -* `sys.hardware_addresses` +- `sys.ipv4_N[iface]` +- `sys.ip2iface` +- `sys.ipaddresses` +- `sys.interface_flags` +- `sys.inet` +- `sys.inet6` +- `sys.hardware_mac[iface]` +- `sys.hardware_addresses` **History:** -* Introduced in CFEngine 3.10.0 -* Preferred location moved from `$(sys.inputdir)` to `$(sys.workdir)` in CFEngine 3.23.0 +- Introduced in CFEngine 3.10.0 +- Preferred location moved from `$(sys.inputdir)` to `$(sys.workdir)` in CFEngine 3.23.0 ## Binary files in /var/cfengine -* `randseed` +- `randseed` ## git in /var/cfengine/bin -* `bin/git` -* `bin/git-cvsserver` -* `bin/gitk` -* `bin/git-receive-pack` -* `bin/git-shell` -* `bin/git-upload-archive` -* `bin/git-upload-pack` +- `bin/git` +- `bin/git-cvsserver` +- `bin/gitk` +- `bin/git-receive-pack` +- `bin/git-shell` +- `bin/git-upload-archive` +- `bin/git-upload-pack` ## Misc. in /var/cfengine/bin -* `bin/curl` -* `bin/lmdump` -* `bin/openssl` -* `bin/rpmvercmp` -* `bin/rsync` -* `bin/runalerts.sh` +- `bin/curl` +- `bin/lmdump` +- `bin/openssl` +- `bin/rpmvercmp` +- `bin/rsync` +- `bin/runalerts.sh` ## Postgres in /var/cfengine/bin -* `bin/clusterdb` -* `bin/createdb` -* `bin/createlang` -* `bin/createuser` -* `bin/dropdb` -* `bin/droplang` -* `bin/dropuser` -* `bin/initdb` -* `bin/pg_basebackup` -* `bin/pg_config` -* `bin/pg_controldata` -* `bin/pg_ctl` -* `bin/pg_dump` -* `bin/pg_dumpall` -* `bin/pg_isready` -* `bin/pg_receivexlog` -* `bin/pg_resetxlog` -* `bin/pg_restore` -* `bin/postgres` -* `bin/postmaster` -* `bin/psql` -* `bin/reindexdb` -* `bin/vacuumdb` +- `bin/clusterdb` +- `bin/createdb` +- `bin/createlang` +- `bin/createuser` +- `bin/dropdb` +- `bin/droplang` +- `bin/dropuser` +- `bin/initdb` +- `bin/pg_basebackup` +- `bin/pg_config` +- `bin/pg_controldata` +- `bin/pg_ctl` +- `bin/pg_dump` +- `bin/pg_dumpall` +- `bin/pg_isready` +- `bin/pg_receivexlog` +- `bin/pg_resetxlog` +- `bin/pg_restore` +- `bin/postgres` +- `bin/postmaster` +- `bin/psql` +- `bin/reindexdb` +- `bin/vacuumdb` ## Not verified -* `state/history.lmdb` +- `state/history.lmdb` CFEngine Enterprise maintains this long-term trend database. -* `state/cf_observations.lmdb` +- `state/cf_observations.lmdb` This database contains the current state of the observational history of the host as recorded by `cf-monitord`. -* `state/cf_state.lmdb` +- `state/cf_state.lmdb` A database of persistent classes active on this current host. -* `state/nova_measures.lmdb` +- `state/nova_measures.lmdb` CFEngine Enterprise database of custom measurements. -* `state/nova_static.lmdb` +- `state/nova_static.lmdb` CFEngine Enterprise database of static system discovery data. -* `state/cf_procs` -A cache of the process table. This is useful for `measurement` promises about processes. +- `state/cf_procs` + A cache of the process table. This is useful for `measurement` promises about processes. -* `state/cf_rootprocs` -A cache of the process table of processes owned by the root user. This is useful for `measurement` promises about processes. +- `state/cf_rootprocs` + A cache of the process table of processes owned by the root user. This is useful for `measurement` promises about processes. -* `state/cf_otherprocs` -A cache of the process table for processes not owned by the root user. This is useful for `measurement` promises about processes. +- `state/cf_otherprocs` + A cache of the process table for processes not owned by the root user. This is useful for `measurement` promises about processes. -* `state/file_changes.log` +- `state/file_changes.log` A time-stamped log of which files have experienced content changes since the last observation, as determined by the hashing algorithms in CFEngine. -* `state/*_measure.log` +- `state/*_measure.log` CFEngine Enterprise maintains user-defined logs based on specifically promised observations of the system. -* `state/env_data` +- `state/env_data` This file contains a list of currently discovered classes and variable values that characterize the anomaly alert environment. They are altered by the monitor daemon. -* `/var/logs/CFEngine-Install.log` +- `/var/logs/CFEngine-Install.log` This file contains logs related to the CFEngine package installation. diff --git a/content/overview/glossary.markdown b/content/overview/glossary.markdown index 630653ff4..e36135d0e 100644 --- a/content/overview/glossary.markdown +++ b/content/overview/glossary.markdown @@ -205,9 +205,9 @@ This might be reusable bundles of promises, or bodies. Log files tell you some historical, usually timestamped, information about events that happened in the past. In CFEngine, there are a few notable log files: -* `/var/logs/CFEngineInstall.log` - Information about the installation, especially useful if installing the package failed. -* `/var/cfengine/outputs/` - Output logs of previous scheduled agent runs (if any). -* `/var/cfengine/httpd/logs/error_log` - Apache errors (Mission Portal / API) +- `/var/logs/CFEngineInstall.log` - Information about the installation, especially useful if installing the package failed. +- `/var/cfengine/outputs/` - Output logs of previous scheduled agent runs (if any). +- `/var/cfengine/httpd/logs/error_log` - Apache errors (Mission Portal / API) #### Mission Portal (MP) @@ -218,8 +218,8 @@ Name of the user interface used in commercial CFEngine editions, where all repor Namespaces allow you to define new scopes for bundles, variables, and classes. By using a specific name for the namespace, you can use short and generic names for the identifiers inside of it. -By default, if you don't specify a namespace, you are using the namespace called ```default```. -The CMDB (group data / host-specific data in Mission Portal) uses the ```data``` namespace unless you specify a namespace. +By default, if you don't specify a namespace, you are using the namespace called `default`. +The CMDB (group data / host-specific data in Mission Portal) uses the `data` namespace unless you specify a namespace. You can think of namespaces in a similar way as putting files inside folders, instead of having all of your files in one folder. The result is that things are more organized and less chances of files / classes / variables / bundles having conflicting names. @@ -246,7 +246,7 @@ Platforms are described using short identifiers, e.g., RH5, REL5, SuSE 11, SLES, #### Policy server -The special server that others consult for the latest policies is called the *policy server*. +The special server that others consult for the latest policies is called the _policy server_. Typically the policy server is set by the bootstrapping process. diff --git a/content/overview/how-cfengine-works.markdown b/content/overview/how-cfengine-works.markdown index 9f391f10d..4caebed42 100644 --- a/content/overview/how-cfengine-works.markdown +++ b/content/overview/how-cfengine-works.markdown @@ -44,13 +44,13 @@ customers, all data is also stored in a local database. CFEngine also stores a large number of asset information like software installed, CPU, memory, disk, network activity, etc. As for execution results, CFEngine can have 3 states: -* **Promise Kept**: Actual state was equal to Desired State +- **Promise Kept**: Actual state was equal to Desired State -* **Promise Repaired**: Actual state was not equal to Desired State, but the -agent was able to repair the state into compliance +- **Promise Repaired**: Actual state was not equal to Desired State, but the + agent was able to repair the state into compliance -* **Promise not Kept**: Actual state was not equal to Desired state and the -agent was not able to restore into compliance +- **Promise not Kept**: Actual state was not equal to Desired state and the + agent was not able to restore into compliance @@ -88,7 +88,7 @@ long run. ### The Mission plan -At CFEngine, we refer to the management of your datacentre as *The Mission*. The +At CFEngine, we refer to the management of your datacentre as _The Mission_. The diagram below shows the main steps in preparing mission control. Some training is recommended, and as much planning as you can manage in advance. Once a mission is underway, you should expect to work by making small corrections to @@ -135,7 +135,7 @@ in a team that embraces its methods. The CFEngine team will become the enabler of business agility, security, reliability and standardization. The CFEngine team needs to have administrator or super-user access to systems, -and it needs the *headroom* or *slack* to think strategically. It needs to build +and it needs the _headroom_ or _slack_ to think strategically. It needs to build up processes and workflows that address quality assurance and minimize the risk of change. @@ -183,7 +183,7 @@ these commitments in terms of CFEngine promises. The four mission phases are sometimes referred to as -* Build +- Build A mission is based on decisions and resources that need to be put assembled or `built` before they can be applied. This is the planning phase. @@ -193,32 +193,33 @@ The four mission phases are sometimes referred to as promises, the system will function seamlessly as planned. This is how it works in a human organization, and this is how is works for computers too. -* Deploy +- Deploy - Deploying really means launching the policy into production. In CFEngine you - simply publish your policy (in CFEngine parlance these are `promise - proposals`) and the machines see the new proposals and can adjust - accordingly. Each machine runs an agent that is capable of keeping the - system on course and maintaining it over time without further assistance. + Deploying really means launching the policy into production. In CFEngine you + simply publish your policy (in CFEngine parlance these are `promise + proposals`) and the machines see the new proposals and can adjust + accordingly. Each machine runs an agent that is capable of keeping the + system on course and maintaining it over time without further assistance. -* Manage +- Manage - Once a decision is made, unplanned events will occur. Such incidents - traditionally set off alarms and humans rush to make new transactions to - repair them. Under CFEngine guidance, the autonomous agent manages the - system, and humans only manage knowledge and have to deal with rare events - that cannot be dealt with automatically. + Once a decision is made, unplanned events will occur. Such incidents + traditionally set off alarms and humans rush to make new transactions to + repair them. Under CFEngine guidance, the autonomous agent manages the + system, and humans only manage knowledge and have to deal with rare events + that cannot be dealt with automatically. -* Audit +- Audit - CFEngine performs continuous analysis and correction, and commercial - editions generate explicit reports on mission status. Users can sit back and - examine these reports to check mission progress, or examine the current - state in relation to the knowledge map for the mission. + CFEngine performs continuous analysis and correction, and commercial + editions generate explicit reports on mission status. Users can sit back and + examine these reports to check mission progress, or examine the current + state in relation to the knowledge map for the mission. [Contact CFEngine](https://cfengine.com/contact) ## CFEngine architecture and design + CFEngine operates autonomously in a network, under your guidance. While CFEngine supports anything from 1 servers to 100,000+ servers, the essence of any CFEngine deployment is the same. diff --git a/content/reference/_index.markdown b/content/reference/_index.markdown index 61c746d4b..41d2d0ed7 100644 --- a/content/reference/_index.markdown +++ b/content/reference/_index.markdown @@ -10,15 +10,15 @@ components, bodies, functions, variables, classes and attributes in detail. Language elements that belong together are typically documented on the same page. -* [Components][Components] -* [Promise types][Promise types] -* [Functions][Functions] -* [Language concepts][Language concepts] -* [Special variables][Special variables] -* [Enterprise API reference][Enterprise API reference] -* [Syntax, identifiers and names][Language concepts#Syntax, identifiers and names] -* [Masterfiles Policy Framework][Masterfiles Policy Framework] -* [All promise and body types][All promise and body types] -* [Macros][Macros] +- [Components][Components] +- [Promise types][Promise types] +- [Functions][Functions] +- [Language concepts][Language concepts] +- [Special variables][Special variables] +- [Enterprise API reference][Enterprise API reference] +- [Syntax, identifiers and names][Language concepts#Syntax, identifiers and names] +- [Masterfiles Policy Framework][Masterfiles Policy Framework] +- [All promise and body types][All promise and body types] +- [Macros][Macros] See also: [All promise types][All promise and body types#All promise types], [All body Types][All promise and body types#All body Types] diff --git a/content/reference/all-types.markdown b/content/reference/all-types.markdown index 7a9d68dea..f4ff5158d 100644 --- a/content/reference/all-types.markdown +++ b/content/reference/all-types.markdown @@ -4,8 +4,8 @@ title: All promise and body types sorting: 110 --- -* [All promise types][All promise and body types#All promise types] -* [All body Types][All promise and body types#All body Types] +- [All promise types][All promise and body types#All promise types] +- [All body Types][All promise and body types#All body Types] ## All promise types diff --git a/content/reference/components/_index.markdown b/content/reference/components/_index.markdown index bfe9cc4a9..90ff9b02a 100644 --- a/content/reference/components/_index.markdown +++ b/content/reference/components/_index.markdown @@ -131,7 +131,7 @@ you expect your policies to be run by older version, you'll need an explicit ### bwlimit **Description:** Coarse control of bandwidth any cf-serverd or cf-agent process -will send *out*. In Bytes/sec. +will send _out_. In Bytes/sec. Bandwidth limit is meant to set an upper bound of traffic coming out of CFEngine agents or servers, as a countermeasure against network abuse from them. The limit @@ -158,19 +158,19 @@ body common control } ``` -In this example, bwlimit is set to 10MBytes/sec = 80Mbit/s meaning that +In this example, bwlimit is set to 10MBytes/sec = 80Mbit/s meaning that CFEngine would only consume up to ~80% of any 100Mbit ethernet interface. ### cache_system_functions **Description:** Controls the caching of the results of system functions, e.g. `execresult()` and `returnszero()` for shell execution and -`ldapvalue()` and friends for LDAP queries. Without this setting, +`ldapvalue()` and friends for LDAP queries. Without this setting, CFEngine's evaluation model will evaluate functions multiple times, -which is a performance concern. See [`Functions`][Functions]. +which is a performance concern. See [`Functions`][Functions]. Although you can override this to `false`, in practice you should -almost never need to do so. The effect of having it `true` (the +almost never need to do so. The effect of having it `true` (the default) is that the expensive functions will be run just once and then their result will be cached. @@ -190,6 +190,7 @@ cache_system_functions => "true"; **See also:** [`ifelapsed` in action bodies][Promise types#ifelapsed] **History:** + - Introduced in version 3.6.0. ### domain @@ -318,14 +319,14 @@ inputs => { If no filenames are specified, no other filenames will be included in the compilation process. -Library contents are checked for duplication by path and by hash. For +Library contents are checked for duplication by path and by hash. For example, if you put `library.cf` twice in your `inputs`, the duplicate -`library.cf` is noticed because the same path is included twice. A +`library.cf` is noticed because the same path is included twice. A verbose-level message is emitted but otherwise there is no error. In addition, if you include a file once with path `/x/y/z.cf` and again with path `/x/./y/z.cf`, the duplicate file will be rejected -regardless of any path tricks or symbolic links. The contents are +regardless of any path tricks or symbolic links. The contents are hashed, so the same file can't be included twice. ### lastseenexpireafter @@ -426,12 +427,12 @@ body common control using the [`body copy_from protocol_version`][files#protocol_version] attribute. When undefined (the default) peers automatically negotiate the latest protocol version. -**See also:** [`body copy_from protocol_version`][files#protocol_version], `allowlegacyconnects`, [`allowtlsversion`][cf-serverd#allowtlsversion], [`allowciphers`][cf-serverd#allowciphers], [`tls_min_version`][Components#tls_min_version], [`tls_ciphers`][Components#tls_ciphers], [`encrypt`][files#encrypt], [`logencryptedtransfers`][cf-serverd#logencryptedtransfers], [`ifencrypted`][access#ifencrypted] +**See also:** [`body copy_from protocol_version`][files#protocol_version], `allowlegacyconnects`, [`allowtlsversion`][cf-serverd#allowtlsversion], [`allowciphers`][cf-serverd#allowciphers], [`tls_min_version`][Components#tls_min_version], [`tls_ciphers`][Components#tls_ciphers], [`encrypt`][files#encrypt], [`logencryptedtransfers`][cf-serverd#logencryptedtransfers], [`ifencrypted`][access#ifencrypted] **History:** -* Introduced in CFEngine 3.6.0 with `protocol_version` `1` (`classic`) and `protocol_version` `2` (`tls`) -* Added `protocol_version` `3` (`cookie`) in CFEngine 3.15.0 +- Introduced in CFEngine 3.6.0 with `protocol_version` `1` (`classic`) and `protocol_version` `2` (`tls`) +- Added `protocol_version` `3` (`cookie`) in CFEngine 3.15.0 ### require_comments @@ -502,7 +503,7 @@ CFEngine's components may promise to send data. **Allowed input range:** `[a-zA-Z0-9_$(){}.:-]+` -**Default value:** ```localhost``` +**Default value:** `localhost` **Example:** @@ -526,7 +527,7 @@ components may promise to send data. **Allowed input range:** `0,99999999999` -**Default value:** ```514``` +**Default value:** `514` **Example:** @@ -565,7 +566,7 @@ body common control **History:** -* Introduced in 3.19.0, 3.18.1 +- Introduced in 3.19.0, 3.18.1 ### tls_ciphers @@ -638,5 +639,5 @@ of CFEngine, but today they are deprecated, either because their functionality is being handled trasparently or because it doesn't apply to current CFEngine version. -* fips_mode -* host_licenses_paid +- fips_mode +- host_licenses_paid diff --git a/content/reference/components/cf-agent.markdown b/content/reference/components/cf-agent.markdown index 6113e353f..d41063e2b 100644 --- a/content/reference/components/cf-agent.markdown +++ b/content/reference/components/cf-agent.markdown @@ -17,7 +17,7 @@ affected by `common` and `agent` control bodies. **Notes:** -* `cf-agent` always considers the class ```agent``` to be defined. +- `cf-agent` always considers the class `agent` to be defined. ## Command reference @@ -28,7 +28,7 @@ affected by `common` and `agent` control bodies. Like the `--dry-run` option, the `--simulate` option tries to identify changes to your system without making changes to the system, however it goes further than `--dry-run` by making changes in a `chroot` and making a distinction -between *safe* and *unsafe* functions, e.g. `execresult()`. +between _safe_ and _unsafe_ functions, e.g. `execresult()`. The agent will execute promises with unsafe functions when the `--simulate` options is given only if the promise using the function is tagged `simulate_safe`. @@ -48,37 +48,38 @@ bundle agent __main__ The simulate option takes a parameter, `diff`, `manifest`, or `manifest-full` which is used to determine the summary output shown at the end of the run. -* `diff` - Show only things that changed during the simulated run. -* `manifest` - Show files and packages changed by the simulated run. -* `manifest-full` - Show all files evaluated by the simulated run (including unchanged ones) +- `diff` - Show only things that changed during the simulated run. +- `manifest` - Show files and packages changed by the simulated run. +- `manifest-full` - Show all files evaluated by the simulated run (including unchanged ones) + - cf-agent can now simulate the changes done to files in a chroot, printing + diff or manifest information about what it would do in a normal evaluation. + Use the new command line option: `--simulate=diff` or `--simulate=manifest`. + Please note that only files and packages promises are simulated currently. - - cf-agent can now simulate the changes done to files in a chroot, printing - diff or manifest information about what it would do in a normal evaluation. - Use the new command line option: `--simulate=diff` or `--simulate=manifest`. - Please note that only files and packages promises are simulated currently. - - - Added a new --simulate=manifest-full mode - New simulation mode that manifests all changed files as well as - all other files evaluated by the agent run which were not skipped - (by file selection rules) (CFE-3506) + - Added a new --simulate=manifest-full mode + New simulation mode that manifests all changed files as well as + all other files evaluated by the agent run which were not skipped + (by file selection rules) (CFE-3506) #### Notes -* Supported on Linux for `files` and `packages` type promises + +- Supported on Linux for `files` and `packages` type promises #### History -* Introduced in version 3.17.0 -* `--simulate=manifest-full` introduced in version 3.18.0 + +- Introduced in version 3.17.0 +- `--simulate=manifest-full` introduced in version 3.18.0 ## Automatic bootstrapping Automatic bootstrapping allows the user to connect a CFEngine Host to a Policy -Server without specifying the IP address manually. It uses the *Avahi* service +Server without specifying the IP address manually. It uses the _Avahi_ service discovery implementation of `zeroconf` to locate the Policy Server, obtain its IP address, and then connect to it. To use automatic bootstrap, install the following Avahi libraries: -* libavahi-client -* libavahi-common +- libavahi-client +- libavahi-common To make the CFEngine Server discoverable, it needs to register itself as an Avahi service. Run the following command: @@ -359,6 +360,7 @@ syslog facility level. ```cf3 agentfacility => "LOG_USER"; ``` + **Notes:** This is ignored on Windows, as CFEngine Enterprise creates event logs. @@ -477,7 +479,7 @@ body agent control ### childlibpath -**Description:** The `childlibpath` string contains the LD\_LIBRARY\_PATH +**Description:** The `childlibpath` string contains the LD_LIBRARY_PATH for child processes. This string may be used to set the internal `LD_LIBRARY_PATH` environment @@ -515,7 +517,8 @@ body agent control **See also:** `admit_keys`, `controls/cf_agent.cf` **History:** -* Introduced in 3.20.0 + +- Introduced in 3.20.0 ### default_repository @@ -550,7 +553,7 @@ stored in an alternative repository as `_usr_local_etc_postfix.conf.cfsaved`. If unset then backups are stored in the same directory as the original file with an identifying suffix. -**See also:** [`edit_backup` in ```body edit_defaults```][files#edit_backup], [`copy_backup` in ```body copy_from```][files#copy_backup] +**See also:** [`edit_backup` in `body edit_defaults`][files#edit_backup], [`copy_backup` in `body copy_from`][files#copy_backup] ### default_timeout @@ -575,7 +578,7 @@ body agent control **Notes:** -* `cf-serverd` will time out any transfer that takes longer than 10 minutes +- `cf-serverd` will time out any transfer that takes longer than 10 minutes (this is not currently tunable). ### defaultcopytype @@ -860,16 +863,16 @@ body agent control **Notes:** -* A value of `0` means no locking, all promises will be executed each execution if in context. This also disables function caching. -* This is not a reliable way to control frequency over a long period of time. -* Locks provide simple but weak frequency control. -* Locks older than 4 weeks are automatically purged. +- A value of `0` means no locking, all promises will be executed each execution if in context. This also disables function caching. +- This is not a reliable way to control frequency over a long period of time. +- Locks provide simple but weak frequency control. +- Locks older than 4 weeks are automatically purged. **See also:** [Promise locking][Promises#Promise locking], [ifelapsed action body attribute][Promise types#ifelapsed] ### inform -**Description:** The `inform` menu option policy sets the default output +**Description:** The `inform` menu option policy sets the default output level 'permanently' within the class context indicated. It is equivalent to (and when present, overrides) the command line option @@ -1022,7 +1025,7 @@ body agent control This examples uses a non-empty list with the name 'none'. This is not a reserved word, but as long as there are no bundles with the name 'none' this -has the effect of *never* reloading the process table. This keeps improves the +has the effect of _never_ reloading the process table. This keeps improves the efficiency of the agent. **History:** Was introduced in version 3.1.3, Enterprise 2.0.2 (2010) @@ -1081,20 +1084,20 @@ body agent control **History:** -* Added in 3.9.0 +- Added in 3.9.0 **Notes:** -* Available in CFEngine Enterprise. -* Persistent classes are logged with the timestamp of each agent run. +- Available in CFEngine Enterprise. +- Persistent classes are logged with the timestamp of each agent run. The following classes are excluded from logging: -* Time based classes (`Hr01`, `Tuesday`, `Morning`, etc ...) -* `license_expired` -* `any` -* `from_cfexecd` -* Life cycle (`Lcycle_0`, `GMT_Lcycle_3`) +- Time based classes (`Hr01`, `Tuesday`, `Morning`, etc ...) +- `license_expired` +- `any` +- `from_cfexecd` +- Life cycle (`Lcycle_0`, `GMT_Lcycle_3`) ### secureinput @@ -1120,7 +1123,7 @@ body agent control ### select_end_match_eof **Description:** When `true` this sets the default behavior for `edit_line` -promises to allow the end of a file to mark the end of a region when ```select_end``` +promises to allow the end of a file to mark the end of a region when `select_end` is defined, but not found. It is useful for configuration files with sections that do not have end markers, diff --git a/content/reference/components/cf-execd.markdown b/content/reference/components/cf-execd.markdown index 8f73bdbb6..8113e4d00 100644 --- a/content/reference/components/cf-execd.markdown +++ b/content/reference/components/cf-execd.markdown @@ -18,8 +18,8 @@ network. **Notes:** -* This daemon reloads it's config when the SIGHUP signal is received. -* `cf-execd` always considers the class ```executor``` to be defined. +- This daemon reloads it's config when the SIGHUP signal is received. +- `cf-execd` always considers the class `executor` to be defined. **History:** @@ -383,7 +383,7 @@ means for setting splay times. **Notes:** -* By default, in the Masterfiles Policy Framework, `cfapache` is allowed to access the socket on Enterprise Hubs. +- By default, in the Masterfiles Policy Framework, `cfapache` is allowed to access the socket on Enterprise Hubs. **Example:** @@ -398,7 +398,7 @@ body executor control **History:** -* 3.18.0 Added `runagent_socket_allow_users` attribute +- 3.18.0 Added `runagent_socket_allow_users` attribute ## Sockets @@ -408,7 +408,7 @@ The `body executor control` attribute `runagent_socket_allow_users` controls the **Notes:** -* Unlike execution triggered with the `cf-runagent` binary, there is currently no capability to define additional options like defining additional classes, or the remote bundlesequence. +- Unlike execution triggered with the `cf-runagent` binary, there is currently no capability to define additional options like defining additional classes, or the remote bundlesequence. **Example:** @@ -422,4 +422,4 @@ echo 'host001' > /var/cfengine/state/cf-execd.sockets/cf-runagent.socket **History:** -* 3.18.0 Added socket for triggering `cf-runagent` by hostname or IP. +- 3.18.0 Added socket for triggering `cf-runagent` by hostname or IP. diff --git a/content/reference/components/cf-hub.markdown b/content/reference/components/cf-hub.markdown index 1f843b5e6..35020d535 100644 --- a/content/reference/components/cf-hub.markdown +++ b/content/reference/components/cf-hub.markdown @@ -16,12 +16,12 @@ that have registered a connection with a collocated `cf-serverd` `common` and `hub` control bodies. `cf-hub` collects data generated from the default run only, what you'd -get if you ran `cf-agent` without specifying a file name. This is to +get if you ran `cf-agent` without specifying a file name. This is to avoid reporting on data generated by test or extraordinary executions. **Notes:** -* `cf-hub` always considers the class ```hub``` to be defined. +- `cf-hub` always considers the class `hub` to be defined. ## Command reference @@ -41,7 +41,7 @@ export_zenoss => "/var/www/reports/summary.z"; **Description:** A list of IP addresses of hosts to exclude from report collection -This list of IP addresses will not be queried for reports by ```cf-hub```, even +This list of IP addresses will not be queried for reports by `cf-hub`, even though they are in the last-seen database. The lists may contain network addresses in CIDR notation or regular @@ -121,7 +121,7 @@ The total time it uses for one host before giving up can be up to 10 times the c Also note that this value is passed to the underlying OS code (`select()`), there is no guarantee that it will wait for that long. -This parameter can also be set using the command line option, ```--query-timeout```. +This parameter can also be set using the command line option, `--query-timeout`. If specified in both policy and command line, the command line option takes precedence. If one of the options (command line or policy) specifies `0`, the other one is used. If both are not specified (or `0`), the default is used. @@ -197,5 +197,5 @@ client_history_timeout => 6; **History:** -* deprecated in 3.6.0 -* introduced in version 3.1.0, Enterprise 2.0.0 (2010) +- deprecated in 3.6.0 +- introduced in version 3.1.0, Enterprise 2.0.0 (2010) diff --git a/content/reference/components/cf-key.markdown b/content/reference/components/cf-key.markdown index 9e349fe71..3718b7e56 100644 --- a/content/reference/components/cf-key.markdown +++ b/content/reference/components/cf-key.markdown @@ -8,7 +8,7 @@ The CFEngine key generator makes key pairs for [remote authentication][Client se **Notes:** -* `cf-key` always considers the class ```keygenerator``` to be defined. +- `cf-key` always considers the class `keygenerator` to be defined. ## Command reference diff --git a/content/reference/components/cf-monitord.markdown b/content/reference/components/cf-monitord.markdown index cbeabb87f..43efd5758 100644 --- a/content/reference/components/cf-monitord.markdown +++ b/content/reference/components/cf-monitord.markdown @@ -17,7 +17,7 @@ affected by `common` and `monitor` control bodies. **Notes:** -* `cf-monitord` always considers the class `monitor` to be defined. +- `cf-monitord` always considers the class `monitor` to be defined. ## Command reference @@ -34,42 +34,42 @@ currently has less support for out-of-the-box probes. 3. otherprocs: Non-privileged process 4. diskfree: Free disk on / partition 5. loadavg: % kernel load utilization -6. netbiosns\_in: netbios name lookups (in) -7. netbiosns\_out: netbios name lookups (out) -8. netbiosdgm\_in: netbios name datagrams (in) -9. netbiosdgm\_out: netbios name datagrams (out) -10. netbiosssn\_in: netbios name sessions (in) -11. netbiosssn\_out: netbios name sessions (out) -12. irc\_in: IRC connections (in) -13. irc\_out: IRC connections (out) -14. cfengine\_in: CFEngine connections (in) -15. cfengine\_out: CFEngine connections (out) -16. nfsd\_in: nfs connections (in) -17. nfsd\_out: nfs connections (out) -18. smtp\_in: smtp connections (in) -19. smtp\_out: smtp connections (out) -20. www\_in: www connections (in) -21. www\_out: www connections (out) -22. ftp\_in: ftp connections (in) -23. ftp\_out: ftp connections (out) -24. ssh\_in: ssh connections (in) -25. ssh\_out: ssh connections (out) -26. wwws\_in: wwws connections (in) -27. wwws\_out: wwws connections (out) -28. icmp\_in: ICMP packets (in) -29. icmp\_out: ICMP packets (out) -30. udp\_in: UDP dgrams (in) -31. udp\_out: UDP dgrams (out) -32. dns\_in: DNS requests (in) -33. dns\_out: DNS requests (out) -34. tcpsyn\_in: TCP sessions (in) -35. tcpsyn\_out: TCP sessions (out) -36. tcpack\_in: TCP acks (in) -37. tcpack\_out: TCP acks (out) -38. tcpfin\_in: TCP finish (in) -39. tcpfin\_out: TCP finish (out) -40. tcpmisc\_in: TCP misc (in) -41. tcpmisc\_out: TCP misc (out) +6. netbiosns_in: netbios name lookups (in) +7. netbiosns_out: netbios name lookups (out) +8. netbiosdgm_in: netbios name datagrams (in) +9. netbiosdgm_out: netbios name datagrams (out) +10. netbiosssn_in: netbios name sessions (in) +11. netbiosssn_out: netbios name sessions (out) +12. irc_in: IRC connections (in) +13. irc_out: IRC connections (out) +14. cfengine_in: CFEngine connections (in) +15. cfengine_out: CFEngine connections (out) +16. nfsd_in: nfs connections (in) +17. nfsd_out: nfs connections (out) +18. smtp_in: smtp connections (in) +19. smtp_out: smtp connections (out) +20. www_in: www connections (in) +21. www_out: www connections (out) +22. ftp_in: ftp connections (in) +23. ftp_out: ftp connections (out) +24. ssh_in: ssh connections (in) +25. ssh_out: ssh connections (out) +26. wwws_in: wwws connections (in) +27. wwws_out: wwws connections (out) +28. icmp_in: ICMP packets (in) +29. icmp_out: ICMP packets (out) +30. udp_in: UDP dgrams (in) +31. udp_out: UDP dgrams (out) +32. dns_in: DNS requests (in) +33. dns_out: DNS requests (out) +34. tcpsyn_in: TCP sessions (in) +35. tcpsyn_out: TCP sessions (out) +36. tcpack_in: TCP acks (in) +37. tcpack_out: TCP acks (out) +38. tcpfin_in: TCP finish (in) +39. tcpfin_out: TCP finish (out) +40. tcpmisc_in: TCP misc (in) +41. tcpmisc_out: TCP misc (out) 42. webaccess: Webserver hits 43. weberrors: Webserver errors 44. syslog: New log entries (Syslog) @@ -83,32 +83,32 @@ currently has less support for out-of-the-box probes. 52. cpu1: %CPU utilization core 1 53. cpu2: %CPU utilization core 2 54. cpu3: %CPU utilization core 3 -55. microsoft\_ds\_out: Samba/MS\_ds name sessions (out) -56. www\_alt\_in: Alternative web service connections (in) -57. www\_alt\_out: Alternative web client connections (out) -58. imaps\_in: encrypted imap mail service sessions (in) -59. imaps\_out: encrypted imap mail client sessions (out) -60. ldap\_in: LDAP directory service service sessions (in) -61. ldap\_out: LDAP directory service client sessions (out) -62. ldaps\_in: LDAP directory service service sessions (in) -63. ldaps\_out: LDAP directory service client sessions (out) -64. mongo\_in: Mongo database service sessions (in) -65. mongo\_out: Mongo database client sessions (out) -66. mysql\_in: MySQL database service sessions (in) -67. mysql\_out: MySQL database client sessions (out) -68. postgres\_in: PostgreSQL database service sessions (in) -69. postgres\_out: PostgreSQL database client sessions (out) -70. ipp\_in: Internet Printer Protocol (in) -71. ipp\_out: Internet Printer Protocol (out) -72. io\_reads: Number of I/O reads -73. io\_writes: Number of I/O writes -74. io\_readdata: Aggregate mount of data read across all devices -75. io\_writtendata: Aggregate amount of data written across all devices -76. mem\_total: Total system memory -77. mem\_free: Free system memory -78. mem\_cached: Size of disk cache -79. mem\_swap: Total swap size -80. mem\_freeswap: Free swap size +55. microsoft_ds_out: Samba/MS_ds name sessions (out) +56. www_alt_in: Alternative web service connections (in) +57. www_alt_out: Alternative web client connections (out) +58. imaps_in: encrypted imap mail service sessions (in) +59. imaps_out: encrypted imap mail client sessions (out) +60. ldap_in: LDAP directory service service sessions (in) +61. ldap_out: LDAP directory service client sessions (out) +62. ldaps_in: LDAP directory service service sessions (in) +63. ldaps_out: LDAP directory service client sessions (out) +64. mongo_in: Mongo database service sessions (in) +65. mongo_out: Mongo database client sessions (out) +66. mysql_in: MySQL database service sessions (in) +67. mysql_out: MySQL database client sessions (out) +68. postgres_in: PostgreSQL database service sessions (in) +69. postgres_out: PostgreSQL database client sessions (out) +70. ipp_in: Internet Printer Protocol (in) +71. ipp_out: Internet Printer Protocol (out) +72. io_reads: Number of I/O reads +73. io_writes: Number of I/O writes +74. io_readdata: Aggregate mount of data read across all devices +75. io_writtendata: Aggregate amount of data written across all devices +76. mem_total: Total system memory +77. mem_free: Free system memory +78. mem_cached: Size of disk cache +79. mem_swap: Total swap size +80. mem_freeswap: Free swap size Slots with a higher number are used for custom measurement promises in CFEngine Enterprise. @@ -122,14 +122,14 @@ into agent variables in the `$(mon.name)` context. `cf-monitord` records data in `$(sys.statedir)` (typically `/var/cfengine/state`). -* `cf_observations.lmdb` -* `nova_measures.lmdb` -* `ts_key` -* `env_data` -* `cf_incoming.` -* `cf_outgoing.` -* `cf_state.lmdb` -* `history.lmdb` +- `cf_observations.lmdb` +- `nova_measures.lmdb` +- `ts_key` +- `env_data` +- `cf_incoming.` +- `cf_outgoing.` +- `cf_state.lmdb` +- `history.lmdb` ## Statistical classes @@ -140,18 +140,18 @@ depending on the measurement. The following suffixes may be used when defining classes: -* `_high` :: The last measurement seemed high. It was greater than the average of all time and also greater than the recent average. This could indicate that the measured value is experiencing a "spike" or trending in a positive direction. -* `_low` :: The last measurement was low. It was lower than the average of all time and also lower than the recent average. This could indicate that the measured value is experiencing a "dip" or trending in a negative direction. -* `_normal` :: The value was neither high nor low, (as per how those are described above). -* `_ldt` :: A leap (step) detected, meaning a distinct (significant) change in the average. -* `_dev1` :: The last measurement was at least 1 standard deviation higher/lower than the average. -* `_dev2` :: The last measurement was at least 2 standard deviations higher/lower than the average. These classes are persistently defined for a number of minutes. -* `_anomaly` :: The last measurement was at least 3 standard deviations than the average. These classes are persistently defined for a number of minutes. -* `_microanomaly` :: The last measurement was at least 2 standard deviations higher than the average. +- `_high` :: The last measurement seemed high. It was greater than the average of all time and also greater than the recent average. This could indicate that the measured value is experiencing a "spike" or trending in a positive direction. +- `_low` :: The last measurement was low. It was lower than the average of all time and also lower than the recent average. This could indicate that the measured value is experiencing a "dip" or trending in a negative direction. +- `_normal` :: The value was neither high nor low, (as per how those are described above). +- `_ldt` :: A leap (step) detected, meaning a distinct (significant) change in the average. +- `_dev1` :: The last measurement was at least 1 standard deviation higher/lower than the average. +- `_dev2` :: The last measurement was at least 2 standard deviations higher/lower than the average. These classes are persistently defined for a number of minutes. +- `_anomaly` :: The last measurement was at least 3 standard deviations than the average. These classes are persistently defined for a number of minutes. +- `_microanomaly` :: The last measurement was at least 2 standard deviations higher than the average. The following prefixes may be used when defining classes: -* `entropy_` :: +- `entropy_` :: Note: These suffixes and prefixes may be combined, resulting in a class like `rootprocs_high`, `loadavg_high_ldt`, `cpu1_high_dev3`, and `entropy_postgresql_out_low`. diff --git a/content/reference/components/cf-net.markdown b/content/reference/components/cf-net.markdown index f82b24e07..26d7fd44b 100644 --- a/content/reference/components/cf-net.markdown +++ b/content/reference/components/cf-net.markdown @@ -19,7 +19,7 @@ It is in some ways an extremely light-weight version of `cf-agent` - policy eval ## Bootstrapping and cf-key -`cf-net` *needs* a key-pair generated by `cf-key` to communicate with a server. +`cf-net` _needs_ a key-pair generated by `cf-key` to communicate with a server. Thus, the easiest way to use cf-net is on a successfully bootstrapped client: ```console @@ -34,16 +34,18 @@ Connected & authenticated successfully to 'myhostname' All three commands above are run with sudo, so they access the same key file. ## cf-net commands + `cf-net` syntax follows the general structure: ```console $ cf-net [global options] command [command-specific options/arguments] ``` -**Note:** `cf-net` command names are *case insensitive*, so `cf-net get` and `cf-net GET` are equivalent. -All other options, arguments and file names are *case sensitive*. +**Note:** `cf-net` command names are _case insensitive_, so `cf-net get` and `cf-net GET` are equivalent. +All other options, arguments and file names are _case sensitive_. ### Help + **Description:** `cf-net help` is used to access help pages for `cf-net`. **Example:** @@ -66,6 +68,7 @@ Description: Checks if host(s) is available by connecting **Note:** `cf-net --help` cannot be used with arguments like `cf-net help`. ### Connect + **Description:** `cf-net connect` attempts to connect and authenticate to one or more hosts running `cf-serverd`. If no hostname is specified `policy_server.dat` is used (this is true for all `cf-net` commands). @@ -84,6 +87,7 @@ Connected & authenticated successfully to 'myhostname:5308' ``` ### Stat + **Description:** `cf-net stat` is similar to UNIX stat, it gives information about a file/directory. **Example:** @@ -106,6 +110,7 @@ myhostname:5308:'masterfiles' is a directory ``` ### Get + **Description:** Performs a `stat` and then `get` command, downloading the specified file to the current working directory. Use the `-o` option to specify output path. @@ -126,6 +131,7 @@ cfengine test.cf update.cf **Note:** The `-o` option must come before the remote filename: ### Opendir + **Description:** Similar to UNIX `ls`, prints everything inside a directory, in no particular order. **Example:** diff --git a/content/reference/components/cf-promises.markdown b/content/reference/components/cf-promises.markdown index b184391f9..337e0ee25 100644 --- a/content/reference/components/cf-promises.markdown +++ b/content/reference/components/cf-promises.markdown @@ -4,7 +4,7 @@ title: cf-promises sorting: 40 --- -`cf-promises` is a tool for checking CFEngine policy code. It operates by +`cf-promises` is a tool for checking CFEngine policy code. It operates by first parsing policy code checking for syntax errors. Second, it validates the integrity of policy consisting of multiple files. Third, it checks for semantic errors, e.g. specific attribute set rules. Finally, `cf-promises` @@ -13,12 +13,12 @@ many variable and classes promise statements as possible. At no point does `cf-promises` make any changes to the system. In 3.6.0 and later, `cf-promises` will not evaluate function calls -either. This may affect customers who use `execresult` for instance. +either. This may affect customers who use `execresult` for instance. Use the new `--eval-functions yes` command-line option (default is `no`) to retain the old behavior from 3.5.x and earlier. `cf-agent` calls `cf-promises` to validate the policy before running -it. In that case `--eval-functions` is not specified, so functions +it. In that case `--eval-functions` is not specified, so functions are not evaluated prematurely (as you would expect). ## Command reference diff --git a/content/reference/components/cf-reactor.markdown b/content/reference/components/cf-reactor.markdown index 167da1c77..0b3dd2635 100644 --- a/content/reference/components/cf-reactor.markdown +++ b/content/reference/components/cf-reactor.markdown @@ -10,18 +10,18 @@ refreshes the CMDB data file (`host_specific.json`) for the particular host. **Notes:** -* `cf-reactor` is a CFEngine Enterprise hub specific component. +- `cf-reactor` is a CFEngine Enterprise hub specific component. -* Unlike other components there is no control body for `cf-reactor`, all +- Unlike other components there is no control body for `cf-reactor`, all promises are hard coded within the component. -* In the future, the daemon should also take care of inventory refresh for hosts +- In the future, the daemon should also take care of inventory refresh for hosts (now part of `cf-hub`) and many DB maintenance tasks that are now promises in the Masterfiles Policy Framework policy under `/cfe_internal/enterprise`. **History:** -* 3.18.2, 3.20.0 Introduced new component (`cf-reactor`). +- 3.18.2, 3.20.0 Introduced new component (`cf-reactor`). ## Command reference diff --git a/content/reference/components/cf-runagent.markdown b/content/reference/components/cf-runagent.markdown index 83808ddfe..60149224f 100644 --- a/content/reference/components/cf-runagent.markdown +++ b/content/reference/components/cf-runagent.markdown @@ -20,7 +20,7 @@ matching the bundle names. **Notes:** -* `cf-runagent` always considers the class ```runagent``` to be defined. +- `cf-runagent` always considers the class `runagent` to be defined. ## Command reference @@ -303,7 +303,7 @@ body runagent control **Notes:** -* Unlike execution triggered with the `cf-runagent` binary, there is currently no capability to define additional options like defining additional classes, or the remote bundlesequence. +- Unlike execution triggered with the `cf-runagent` binary, there is currently no capability to define additional options like defining additional classes, or the remote bundlesequence. **Example:** @@ -315,4 +315,4 @@ echo 'host001' > /var/cfengine/state/cf-execd.sockets/cf-runagent.socket **History:** -* 3.18.0 Added socket for triggering `cf-runagent` by hostname or IP. +- 3.18.0 Added socket for triggering `cf-runagent` by hostname or IP. diff --git a/content/reference/components/cf-secret.markdown b/content/reference/components/cf-secret.markdown index 8d57ab371..e7cdc72f5 100644 --- a/content/reference/components/cf-secret.markdown +++ b/content/reference/components/cf-secret.markdown @@ -76,4 +76,4 @@ No difference **History:** -* Introduced in 3.16.0, 3.15.3 +- Introduced in 3.16.0, 3.15.3 diff --git a/content/reference/components/cf-serverd.markdown b/content/reference/components/cf-serverd.markdown index 122f9e9a0..54b59f19b 100644 --- a/content/reference/components/cf-serverd.markdown +++ b/content/reference/components/cf-serverd.markdown @@ -9,7 +9,7 @@ keywords: [server] file server for remote file copying and it allows an authorized `cf-runagent` to start a `cf-agent` run. `cf-agent` typically connects to a `cf-serverd` instance to request updated policy code, -but may also request additional files for download. `cf-serverd` employs +but may also request additional files for download. `cf-serverd` employs [role based access control][roles] (defined in policy code) to authorize requests. @@ -18,11 +18,11 @@ affected by `common` and `server` control bodies. **Notes:** -* This daemon reloads it's config when the SIGHUP signal is received. -* If `enable_report_dumps` exists in `WORKDIR` (`/var/cfengine/enable_report_dumps`) `cf-serverd` will log reports provided to `cf-hub` to `WORKDIR/diagnostics/report_dump` (`/var/cfengine/diagnostics/report_dumps`). This data is useful when troubleshooting reporting issues with CFEngine Enterprise. -* `cf-serverd` always considers the class ```server``` to be defined. -* `SIGUSR1` sets the log level to debug. -* `SIGUSR2` sets the log level to notice. +- This daemon reloads it's config when the SIGHUP signal is received. +- If `enable_report_dumps` exists in `WORKDIR` (`/var/cfengine/enable_report_dumps`) `cf-serverd` will log reports provided to `cf-hub` to `WORKDIR/diagnostics/report_dump` (`/var/cfengine/diagnostics/report_dumps`). This data is useful when troubleshooting reporting issues with CFEngine Enterprise. +- `cf-serverd` always considers the class `server` to be defined. +- `SIGUSR1` sets the log level to debug. +- `SIGUSR2` sets the log level to notice. **History:** @@ -318,16 +318,16 @@ collection. The sequence of events is this: -- The host's `cf-serverd` connects to its registered CFEngine Server -- The host identifies itself to authentication and access - control and sends a collect-call pull-request to the server -- The server might honor this, if the access control grants access. -- If access is granted, the server has `collect_window` seconds to - initiate a query to the host for its reports. -- The server identifies itself to authentication and access - control and sends a query request to the host to collect the - reports. -- When finished, the host closes the tunnel. +- The host's `cf-serverd` connects to its registered CFEngine Server +- The host identifies itself to authentication and access + control and sends a collect-call pull-request to the server +- The server might honor this, if the access control grants access. +- If access is granted, the server has `collect_window` seconds to + initiate a query to the host for its reports. +- The server identifies itself to authentication and access + control and sends a query request to the host to collect the + reports. +- When finished, the host closes the tunnel. **Type:** `int` @@ -488,8 +488,8 @@ logencryptedtransfers => "true"; ### maxconnections **Description:** Maximum number of concurrent connections the server - will accept. Recommended value for a hub is **two times the total - number of hosts bootstrapped to this hub**. +will accept. Recommended value for a hub is **two times the total +number of hosts bootstrapped to this hub**. **Type:** `int` @@ -605,7 +605,7 @@ skipverify => { "special_host.*", "192.168\..*" }; ### trustkeysfrom **Description:** List of IPs from whom the server will accept and trust -new (untrusted) public keys. They are denoted in either IP or subnet +new (untrusted) public keys. They are denoted in either IP or subnet form. For compatibility reasons, regular expressions are also accepted. @@ -675,7 +675,7 @@ of CFEngine, but today they are deprecated, either because their functionality is being handled trasparently or because it doesn't apply to current CFEngine version. -* ```auditing``` -* ```dynamicaddresses``` -* ```hostnamekeys``` -* ```keycacheTTL``` +- `auditing` +- `dynamicaddresses` +- `hostnamekeys` +- `keycacheTTL` diff --git a/content/reference/components/cf-support.markdown b/content/reference/components/cf-support.markdown index 9d95fe882..f3235aacb 100644 --- a/content/reference/components/cf-support.markdown +++ b/content/reference/components/cf-support.markdown @@ -15,4 +15,4 @@ The utility will prompt for an optional support ticket number as well as prompt ## History -* Introduced in 3.21.0, 3.18.3 +- Introduced in 3.21.0, 3.18.3 diff --git a/content/reference/functions/_index.markdown b/content/reference/functions/_index.markdown index ec09d5844..c2cfd9fdf 100644 --- a/content/reference/functions/_index.markdown +++ b/content/reference/functions/_index.markdown @@ -62,9 +62,9 @@ change during evaluation, but typically, a class, once defined, will stay define Promise attributes which use a class expression (string) as input, like `if` and `unless`, can take a function call which returns string or boolean as well. -* A boolean function will be resolved to `any`, which is always true, or `!any` +- A boolean function will be resolved to `any`, which is always true, or `!any` which is always false. -* A string function will be resolved, and the returned string will be +- A string function will be resolved, and the returned string will be evaluated as a class expression. ```cf3 @@ -99,12 +99,12 @@ You can get this list automatically with cf-promises --syntax-description json a cf-promises --syntax-description json | jq '.functions | with_entries(select(.value.cached==true)) | keys[]' --> -* `execresult()` and `returnszero()` for shell execution -* `regldap()`, `ldapvalue()`, and `ldaplist()` for LDAP queries -* `findprocesses()`, and `processexists()` for querying processes. -* `host2ip()` and `ip2host()` for DNS queries -* `readtcp()` for TCP interactions -* `hubknowledge()`, and `remotescalar()` for hub queries +- `execresult()` and `returnszero()` for shell execution +- `regldap()`, `ldapvalue()`, and `ldaplist()` for LDAP queries +- `findprocesses()`, and `processexists()` for querying processes. +- `host2ip()` and `ip2host()` for DNS queries +- `readtcp()` for TCP interactions +- `hubknowledge()`, and `remotescalar()` for hub queries When enabled [cached functions](https://docs.cfengine.com/docs/{{site.cfengine.branch}}/search.html?q=The+return+value+is+cached) @@ -115,7 +115,7 @@ and its result will be cached until the end of that agent execution. **Note:** Cached functions are executed multiple times during [policy validation and pre-evaluation][Policy evaluation#cf-promises policy validation step]. -Function caching is *per-process*, so results will not be cached between +Function caching is _per-process_, so results will not be cached between separate components e.g. `cf-agent`, `cf-serverd` and `cf-promises`. Additionally functions are cached by hashing the function arguments. If you have the exact same function call in two different promises (it does not matter if @@ -137,47 +137,47 @@ be evaluated if any argument contains a variable that never resolves. ### Collecting Functions -Some function arguments are marked as *collecting* which means they +Some function arguments are marked as _collecting_ which means they can "collect" an argument from various sources. The data is normalized into the JSON format internally, so all of the following data types have consistent behavior. -* If a key inside a data container is specified (`mycontainer[key]`), -the value under that key is collected. The key can be a string for -JSON objects or a number for JSON arrays. +- If a key inside a data container is specified (`mycontainer[key]`), + the value under that key is collected. The key can be a string for + JSON objects or a number for JSON arrays. -* If a single data container, CFEngine array, or slist is specified -(`mycontainer` or `myarray` or `myslist`), the contents of it are -collected. +- If a single data container, CFEngine array, or slist is specified + (`mycontainer` or `myarray` or `myslist`), the contents of it are + collected. -* If a single data container, CFEngine array, or slist is specified -with `@()` around it (`@(mycontainer)` or `@(myarray)` or -`@(myslist)`), the contents of it are collected. +- If a single data container, CFEngine array, or slist is specified + with `@()` around it (`@(mycontainer)` or `@(myarray)` or + `@(myslist)`), the contents of it are collected. -* If a function call that returns a data container or slist is +- If a function call that returns a data container or slist is specified, that function call is evaluated and the results are inserted, so you can say for instance `sort(data_expand(...), "lex")` to expand a data container then sort it. -* If a list (slist, ilist, or rlist) is named, its entries are collected. +- If a list (slist, ilist, or rlist) is named, its entries are collected. -* If any CFEngine "classic" array (`array[key]`) is named, it's first -converted to a JSON key-value map, then collected. +- If any CFEngine "classic" array (`array[key]`) is named, it's first + converted to a JSON key-value map, then collected. -* If a literal JSON string like `[ 1,2,3 ]` or `{ "x": 500 }` is -provided, it will be parsed and used. +- If a literal JSON string like `[ 1,2,3 ]` or `{ "x": 500 }` is + provided, it will be parsed and used. -* If any of the above-mentioned ways to reference variables are used -**inside** a literal JSON string they will be expanded (or the -function call will fail). This is similar to the behavior of -Javascript, for instance. For example, `mergedata('[ thing, { "mykey": otherthing[123] } ]')` -will wrap the `thing` in a JSON array; then the contents of -`otherthing[123]` will be wrapped in a JSON map which will also go in -the array. +- If any of the above-mentioned ways to reference variables are used + **inside** a literal JSON string they will be expanded (or the + function call will fail). This is similar to the behavior of + Javascript, for instance. For example, `mergedata('[ thing, { "mykey": otherthing[123] } ]')` + will wrap the `thing` in a JSON array; then the contents of + `otherthing[123]` will be wrapped in a JSON map which will also go in + the array. ### Delayed Evaluation Functions -Since CFEngine 3.10, some functions are marked as *delayed evaluation* which +Since CFEngine 3.10, some functions are marked as _delayed evaluation_ which means they can evaluate a function call across every element of a collection. This makes intuitive sense for the collection traversing functions `maparray()`, `maplist()`, and `mapdata()`. diff --git a/content/reference/functions/accumulated.markdown b/content/reference/functions/accumulated.markdown index e7d1c9ff7..dd89d1c83 100644 --- a/content/reference/functions/accumulated.markdown +++ b/content/reference/functions/accumulated.markdown @@ -15,29 +15,29 @@ for example, `accumulated(0,0,0,48,0,0)` or `accumulated(0,0,0,0,90,0)`. **Arguments:** -* `years`, in the range `0,1000` +- `years`, in the range `0,1000` Years of run time. For convenience in conversion, a year of runtime is always 365 days (one year equals 31,536,000 seconds). -* `month`, in the range `0,1000` +- `month`, in the range `0,1000` Months of run time. For convenience in conversion, a month of runtime is always equal to 30 days of runtime (one month equals 2,592,000 seconds). -* `days`, in the range `0,1000` +- `days`, in the range `0,1000` Days of runtime (one day equals 86,400 seconds) -* `hours`, in the range `0,1000` +- `hours`, in the range `0,1000` Hours of runtime -* `minutes`, in the range `0,1000` +- `minutes`, in the range `0,1000` Minutes of runtime 0-59 -* `seconds`, in the range `0,40000` +- `seconds`, in the range `0,40000` Seconds of runtime diff --git a/content/reference/functions/ago.markdown b/content/reference/functions/ago.markdown index 33fe375fa..62550fdd6 100644 --- a/content/reference/functions/ago.markdown +++ b/content/reference/functions/ago.markdown @@ -15,29 +15,29 @@ hours ago". However, you are strongly encouraged to keep your usage of **Arguments:** -* `years`, in the range `0,1000` +- `years`, in the range `0,1000` Years of run time. For convenience in conversion, a year of runtime is always 365 days (one year equals 31,536,000 seconds). -* `month`, in the range `0,1000` +- `month`, in the range `0,1000` Months of run time. For convenience in conversion, a month of runtime is always equal to 30 days of runtime (one month equals 2,592,000 seconds). -* `days`, in the range `0,1000` +- `days`, in the range `0,1000` Days of runtime (one day equals 86,400 seconds) -* `hours`, in the range `0,1000` +- `hours`, in the range `0,1000` Hours of runtime -* `minutes`, in the range `0,1000` +- `minutes`, in the range `0,1000` Minutes of runtime 0-59 -* `seconds`, in the range `0,40000` +- `seconds`, in the range `0,40000` Seconds of runtime diff --git a/content/reference/functions/and.markdown b/content/reference/functions/and.markdown index b4f31a712..19b0a201f 100644 --- a/content/reference/functions/and.markdown +++ b/content/reference/functions/and.markdown @@ -27,5 +27,5 @@ commands: **History:** -* Introduced in 3.2.0, Nova 2.1.0 (2011) -* Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) +- Introduced in 3.2.0, Nova 2.1.0 (2011) +- Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) diff --git a/content/reference/functions/bundlesmatching.markdown b/content/reference/functions/bundlesmatching.markdown index 52d6a5e13..cfac8b0ae 100644 --- a/content/reference/functions/bundlesmatching.markdown +++ b/content/reference/functions/bundlesmatching.markdown @@ -15,11 +15,11 @@ This function searches for the given [anchored][anchored] `name` and `tag1`, Every bundle is prefixed with the namespace, usually `default:`. When any tags are given, only the bundles with those tags are -returned. Bundle tags are set a `tags` variable within a [`meta`][meta] +returned. Bundle tags are set a `tags` variable within a [`meta`][meta] promise; see the example below. This function, used together with the `findfiles` function, allows you -to do dynamic inputs and a dynamic bundle call chain. The dynamic +to do dynamic inputs and a dynamic bundle call chain. The dynamic chain is constrained by an explicit regular expression to avoid accidental or intentional running of unwanted bundles. diff --git a/content/reference/functions/bundlestate.markdown b/content/reference/functions/bundlestate.markdown index 3500e754c..8c0749681 100644 --- a/content/reference/functions/bundlestate.markdown +++ b/content/reference/functions/bundlestate.markdown @@ -34,4 +34,4 @@ Output: **History:** -* Introduced in CFEngine 3.7.0 +- Introduced in CFEngine 3.7.0 diff --git a/content/reference/functions/callstack_callers.markdown b/content/reference/functions/callstack_callers.markdown index 82f8f8826..735497f78 100644 --- a/content/reference/functions/callstack_callers.markdown +++ b/content/reference/functions/callstack_callers.markdown @@ -18,12 +18,12 @@ The returned data container is a list of key-value maps. The maps all have a `type` key and a `frame` key with a counter. For different frames along the stack frame path, the maps have additional keys: -* whenever possible, -* bodies: under key `body` the entry has a full dump of the body policy as JSON, same as what `cf-promises -p json` would produce, using the internal C function `BodyToJson()`. This may include the `line` and `sourcePath` to locate the exact code line. -* bundles: under key `bundle` the entry has a full dump of the bundle policy as JSON, same as what `cf-promises -p json` would produce, using the internal C function `BundleToJson()`. This may include the `line` and `sourcePath` to locate the exact code line. -* promise iteration: the `iteration_index` is recorded -* promises: the `promise_type`, `promiser`, `promise_classes`, and `promise_comment` are recorded -* promise sections (types): the `promise_type` is recorded +- whenever possible, +- bodies: under key `body` the entry has a full dump of the body policy as JSON, same as what `cf-promises -p json` would produce, using the internal C function `BodyToJson()`. This may include the `line` and `sourcePath` to locate the exact code line. +- bundles: under key `bundle` the entry has a full dump of the bundle policy as JSON, same as what `cf-promises -p json` would produce, using the internal C function `BundleToJson()`. This may include the `line` and `sourcePath` to locate the exact code line. +- promise iteration: the `iteration_index` is recorded +- promises: the `promise_type`, `promiser`, `promise_classes`, and `promise_comment` are recorded +- promise sections (types): the `promise_type` is recorded **Example:** diff --git a/content/reference/functions/canonifyuniquely.markdown b/content/reference/functions/canonifyuniquely.markdown index 53c3be4db..d3559fd25 100644 --- a/content/reference/functions/canonifyuniquely.markdown +++ b/content/reference/functions/canonifyuniquely.markdown @@ -8,7 +8,7 @@ title: canonifyuniquely **Description:** Convert an arbitrary string `text` into a unique legal class name. This function turns arbitrary text into class data, appending the -SHA-1 hash for uniqueness. It is exactly equivalent to +SHA-1 hash for uniqueness. It is exactly equivalent to `concat(canonify($(string)), "_", hash($(string),"sha1"));` for a given `$(string)` but is much more convenient to write and remember. diff --git a/content/reference/functions/cf_version_after.markdown b/content/reference/functions/cf_version_after.markdown index 99f2542da..c870b9c02 100644 --- a/content/reference/functions/cf_version_after.markdown +++ b/content/reference/functions/cf_version_after.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/cf_version_at.markdown b/content/reference/functions/cf_version_at.markdown index 75ad7b2f2..2dfaeaa55 100644 --- a/content/reference/functions/cf_version_at.markdown +++ b/content/reference/functions/cf_version_at.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/cf_version_before.markdown b/content/reference/functions/cf_version_before.markdown index 636365c46..aa5063511 100644 --- a/content/reference/functions/cf_version_before.markdown +++ b/content/reference/functions/cf_version_before.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/cf_version_between.markdown b/content/reference/functions/cf_version_between.markdown index 7da23ede1..91e27edd6 100644 --- a/content/reference/functions/cf_version_between.markdown +++ b/content/reference/functions/cf_version_between.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/cf_version_maximum.markdown b/content/reference/functions/cf_version_maximum.markdown index 3caee789f..14c9844ea 100644 --- a/content/reference/functions/cf_version_maximum.markdown +++ b/content/reference/functions/cf_version_maximum.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/cf_version_minimum.markdown b/content/reference/functions/cf_version_minimum.markdown index 37bcc79a5..db4a5e06c 100644 --- a/content/reference/functions/cf_version_minimum.markdown +++ b/content/reference/functions/cf_version_minimum.markdown @@ -21,4 +21,4 @@ Output: **History:** -* Introduced in 3.16.0 +- Introduced in 3.16.0 diff --git a/content/reference/functions/classfiltercsv.markdown b/content/reference/functions/classfiltercsv.markdown index 96ab955d3..f78b3b611 100644 --- a/content/reference/functions/classfiltercsv.markdown +++ b/content/reference/functions/classfiltercsv.markdown @@ -34,17 +34,17 @@ minus `1`. **Notes:** -* If the CSV file is stored in a `git` repository the `.gitattributes` file can be used to ensure proper line endings. +- If the CSV file is stored in a `git` repository the `.gitattributes` file can be used to ensure proper line endings. - For example: + For example: - ``` - # .gitattribtues - *.csv text eol=crlf - RFC-4180-non-compliant-line-endings.csv eol=lf - *.mustache text - *.sh text eol=lf - ``` + ``` + # .gitattribtues + *.csv text eol=crlf + RFC-4180-non-compliant-line-endings.csv eol=lf + *.mustache text + *.sh text eol=lf + ``` **See also:** `classfilterdata()`, `data_expand()`, `readcsv()`, `classmatch()` diff --git a/content/reference/functions/classfilterdata.markdown b/content/reference/functions/classfilterdata.markdown index ae4468432..a1344cf19 100644 --- a/content/reference/functions/classfilterdata.markdown +++ b/content/reference/functions/classfilterdata.markdown @@ -13,6 +13,7 @@ false in the current context. The interpretation of the data container depends on the specified data structure (`data_structure`). If the `data_structure` argument is specified to be: + - `"array_of_arrays"`, the `data_container` argument is interpreted as an array of arrays, and the `key_or_index` argument is interpreted as an index within the children arrays. diff --git a/content/reference/functions/data_readstringarray.markdown b/content/reference/functions/data_readstringarray.markdown index 948fac78a..3a48a692f 100644 --- a/content/reference/functions/data_readstringarray.markdown +++ b/content/reference/functions/data_readstringarray.markdown @@ -7,7 +7,7 @@ title: data_readstringarray **Description:** Returns a data container (map) with up to `maxentries`-1 fields from the first `maxbytes` bytes of file -`filename`. The first field becomes the key in the map. +`filename`. The first field becomes the key in the map. One dimension is separated by the regex `split`, the other by the lines in the file. The array key (the first field) must be unique; if @@ -37,4 +37,4 @@ Output: **History:** -* Added in CFEngine 3.6.0 +- Added in CFEngine 3.6.0 diff --git a/content/reference/functions/data_readstringarrayidx.markdown b/content/reference/functions/data_readstringarrayidx.markdown index af17d80df..1d8b003bd 100644 --- a/content/reference/functions/data_readstringarrayidx.markdown +++ b/content/reference/functions/data_readstringarrayidx.markdown @@ -35,4 +35,4 @@ Output: **History:** -* Added in CFEngine 3.6.0 +- Added in CFEngine 3.6.0 diff --git a/content/reference/functions/data_regextract.markdown b/content/reference/functions/data_regextract.markdown index 0efad01f4..2c4529e74 100644 --- a/content/reference/functions/data_regextract.markdown +++ b/content/reference/functions/data_regextract.markdown @@ -6,7 +6,7 @@ title: data_regextract {{< CFEngine_function_prototype(regex, string) >}} **Description:** Returns a data container filled with backreferences -and named captures if the *multiline* [anchored][anchored] `regex` matches the +and named captures if the _multiline_ [anchored][anchored] `regex` matches the `string`. This function is significantly better than `regextract()` because it @@ -34,7 +34,7 @@ PCRE named captures are described in http://pcre.org/pcre.txt and several syntax (?'name'...) named capturing group (Perl) (?P...) named capturing group (Python) -Since the regular expression is run with /dotall/ and /multiline/ modes, to match the end of a line, use ```[^\n]*``` instead of ```$```. +Since the regular expression is run with /dotall/ and /multiline/ modes, to match the end of a line, use `[^\n]*` instead of `$`. {{< CFEngine_function_attributes(regex, string) >}} diff --git a/content/reference/functions/datastate.markdown b/content/reference/functions/datastate.markdown index 42480f1d1..fb25b562d 100644 --- a/content/reference/functions/datastate.markdown +++ b/content/reference/functions/datastate.markdown @@ -7,15 +7,15 @@ title: datastate **Description:** Returns the current evaluation data state. -The returned data container will have the keys ```classes``` and ```vars```. +The returned data container will have the keys `classes` and `vars`. -Under ```classes``` you'll find a map with the class name as the key and -`true` as the value. Namespaced classes will be prefixed as usual. +Under `classes` you'll find a map with the class name as the key and +`true` as the value. Namespaced classes will be prefixed as usual. -Under ```vars``` you'll find a map with the bundle name as the key -(namespaced if necessary). Under the bundle name you'll find another -map with the variable name as the key. The value is converted to a -data container (JSON format) if necessary. The example should make it +Under `vars` you'll find a map with the bundle name as the key +(namespaced if necessary). Under the bundle name you'll find another +map with the variable name as the key. The value is converted to a +data container (JSON format) if necessary. The example should make it clearer. Mustache templates (see [template_method][files#template_method]), if not given a @@ -35,7 +35,7 @@ Output: **Notes:** -* Beware, when assigning `datastate()` to a variable, multiple passes will result in recursive growth of the data structure. Consider guarding against re-definition of a variable populated by `datastate()`. +- Beware, when assigning `datastate()` to a variable, multiple passes will result in recursive growth of the data structure. Consider guarding against re-definition of a variable populated by `datastate()`. Example illustrating how to prevent recursive growth of variable populated by `datastate()`. @@ -51,4 +51,4 @@ bundle agent main **History:** -* Introduced in CFEngine 3.6.0 +- Introduced in CFEngine 3.6.0 diff --git a/content/reference/functions/eval.markdown b/content/reference/functions/eval.markdown index cf669175a..45ad2da67 100644 --- a/content/reference/functions/eval.markdown +++ b/content/reference/functions/eval.markdown @@ -10,7 +10,7 @@ and `options`. Currently only the `math` and `class` modes with `infix` option are supported for evaluating traditional math expressions. -All the math is done with the C `double` type internally. The results are returned as a string. When the `mode` is `math` the returned value is a floating-point value formatted to 6 decimal places as a string. +All the math is done with the C `double` type internally. The results are returned as a string. When the `mode` is `math` the returned value is a floating-point value formatted to 6 decimal places as a string. `mode` and `options` are optional and default to `math` and `infix`, respectively. @@ -23,7 +23,7 @@ vars: "result" string => eval("200/10", "math", "infix"); ``` -When the `mode` is `class`, the returned string is either false for 0 (`!any`) or true for anything else (`any`) so it can be used in a class expression under `classes`. The `==` operator (see below) is very convenient for this purpose. The actual accepted values for false allow a tiny margin around 0, just like `==`. +When the `mode` is `class`, the returned string is either false for 0 (`!any`) or true for anything else (`any`) so it can be used in a class expression under `classes`. The `==` operator (see below) is very convenient for this purpose. The actual accepted values for false allow a tiny margin around 0, just like `==`. **Example:** @@ -40,13 +40,13 @@ The supported infix mathematical syntax, in order of precedence, is: - `*` and `/` operators for multiplication and division - `%` operators for modulo operation - `+` and `-` operators for addition and subtraction -- `==` "close enough" operator to tell if two expressions evaluate to the same number, with a tiny margin to tolerate floating point errors. It returns 1 or 0. -- `>=` "greater or close enough" operator with a tiny margin to tolerate floating point errors. It returns 1 or 0. -- `>` "greater than" operator. It returns 1 or 0. -- `<=` "less than or close enough" operator with a tiny margin to tolerate floating point errors. It returns 1 or 0. -- `<` "less than" operator. It returns 1 or 0. +- `==` "close enough" operator to tell if two expressions evaluate to the same number, with a tiny margin to tolerate floating point errors. It returns 1 or 0. +- `>=` "greater or close enough" operator with a tiny margin to tolerate floating point errors. It returns 1 or 0. +- `>` "greater than" operator. It returns 1 or 0. +- `<=` "less than or close enough" operator with a tiny margin to tolerate floating point errors. It returns 1 or 0. +- `<` "less than" operator. It returns 1 or 0. -The numbers can be in any format acceptable to the C `scanf` function with the `%lf` format specifier, followed by the `k`, `m`, `g`, `t`, or `p` SI units. So e.g. `-100` and `2.34m` are valid numbers. +The numbers can be in any format acceptable to the C `scanf` function with the `%lf` format specifier, followed by the `k`, `m`, `g`, `t`, or `p` SI units. So e.g. `-100` and `2.34m` are valid numbers. In addition, the following constants are recognized: @@ -81,6 +81,6 @@ The following functions can be used, with parentheses: **History:** -* Function added in 3.6.0. -* `mode` and `options` optional and default to `math` and `infix`, respectively in 3.9.0. -* comparison `<`, `<=`, `>`, `>=` operators added in 3.10.0 +- Function added in 3.6.0. +- `mode` and `options` optional and default to `math` and `infix`, respectively in 3.9.0. +- comparison `<`, `<=`, `>`, `>=` operators added in 3.10.0 diff --git a/content/reference/functions/every.markdown b/content/reference/functions/every.markdown index f214c9d58..f01a146b6 100644 --- a/content/reference/functions/every.markdown +++ b/content/reference/functions/every.markdown @@ -12,11 +12,11 @@ the [unanchored][unanchored] `regex`. **Arguments**: -* `regex` : Regular expression to find, in the range `.*` +- `regex` : Regular expression to find, in the range `.*` -* `list` : The name of the list variable to check, in the range -`[a-zA-Z0-9_$(){}\[\].:]+`. It can be a data container or a regular -list. +- `list` : The name of the list variable to check, in the range + `[a-zA-Z0-9_$(){}\[\].:]+`. It can be a data container or a regular + list. **Example:** diff --git a/content/reference/functions/execresult.markdown b/content/reference/functions/execresult.markdown index a512674c3..f0b4d088b 100644 --- a/content/reference/functions/execresult.markdown +++ b/content/reference/functions/execresult.markdown @@ -39,9 +39,9 @@ operation is beyond CFEngine's ability to guarantee convergence, and on multiple passes and during syntax verification these function calls are executed, resulting in system changes that are **covert**. Calls to `execresult` should be for discovery and information extraction -only. Effectively calls to this function will be also repeatedly +only. Effectively calls to this function will be also repeatedly executed by `cf-promises` when it does syntax checking, which is -highly undesirable if the command is expensive. Consider using +highly undesirable if the command is expensive. Consider using `commands` promises instead, which have locking and are not evaluated by `cf-promises`. @@ -49,5 +49,5 @@ by `cf-promises`. **History:** -* 3.0.5 Newlines no longer replaced with spaces in stored output. -* 3.17.0 Introduced optional parameter `output` added allowing selection of stderr, stdout or both. +- 3.0.5 Newlines no longer replaced with spaces in stored output. +- 3.17.0 Introduced optional parameter `output` added allowing selection of stderr, stdout or both. diff --git a/content/reference/functions/execresult_as_data.markdown b/content/reference/functions/execresult_as_data.markdown index 225940b74..40049f71d 100644 --- a/content/reference/functions/execresult_as_data.markdown +++ b/content/reference/functions/execresult_as_data.markdown @@ -32,4 +32,4 @@ by `cf-promises`. **History:** -* Introduced in 3.17.0 +- Introduced in 3.17.0 diff --git a/content/reference/functions/expandrange.markdown b/content/reference/functions/expandrange.markdown index f0a3958e6..5413694d3 100644 --- a/content/reference/functions/expandrange.markdown +++ b/content/reference/functions/expandrange.markdown @@ -10,7 +10,7 @@ range of integers, in steps specified by the second argument. The function is the inverse of functions like `iprange()` which match patterns of numerical ranges that cannot be represented as regular expressions. The list of strings is composed from the text as quoted - in the first argument, and a numerical range in square brackets is replaced by successive numbers +in the first argument, and a numerical range in square brackets is replaced by successive numbers from the range. {{< CFEngine_function_attributes(string_template, stepsize) >}} diff --git a/content/reference/functions/filesexist.markdown b/content/reference/functions/filesexist.markdown index b9fd96a2d..560ab8e05 100644 --- a/content/reference/functions/filesexist.markdown +++ b/content/reference/functions/filesexist.markdown @@ -14,8 +14,8 @@ this function to return true. **Arguments:** -* list : The name of the list variable or data container to check, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` +- list : The name of the list variable or data container to check, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` **Example:** diff --git a/content/reference/functions/filestat.markdown b/content/reference/functions/filestat.markdown index 29ef7d0ed..c05c65c55 100644 --- a/content/reference/functions/filestat.markdown +++ b/content/reference/functions/filestat.markdown @@ -13,29 +13,29 @@ variable does not expand. **Arguments**: -* `filename` : the file or directory name to inspect, in the range: "?(/.*) -* `field` : the requested field, with the following allowed values: - * `size` : size in bytes - * `gid` : group ID - * `uid` : owner ID - * `ino` : inode number - * `nlink` : number of *hard* links - * `ctime` : time of last change in Unix epoch format - * `atime` : last access time in Unix epoch format - * `mtime` : last modification time in Unix epoch format - * `mode` : file mode as a decimal number - * `modeoct` : file mode as an octal number, e.g. `10777` - * `permstr` : permission string, e.g. `-rwx---rwx` (not available on Windows) - * `permoct` : permissions as an octal number, e.g. `644` (not available on Windows) - * `type` : file type (not available on Windows): `block device`,`character device`, `directory`, `FIFO/pipe`, `symlink`, `regular file`, `socket`, or `unknown` - * `devno` : device number (drive letter on Windows, e.g. `C:`) - * `dev_minor` : minor device number (not available on Windows) - * `dev_major` : major device number (not available on Windows) - * `basename` : the file name minus the directory - * `dirname` : the directory portion of the file name - * `linktarget` : if the file is a `symlink`, its *final* target. The target is chased up to 32 levels of recursion. On Windows, this returns the file name itself. - * `linktarget_shallow` : if the file is a `symlink`, its *first* target. On Windows, this returns the file name itself. - * `xattr` : a string with newline-separated extended attributes and SELinux contexts in `key=valuekey2=value2tag1tag2` format. +- `filename` : the file or directory name to inspect, in the range: "?(/.\*) +- `field` : the requested field, with the following allowed values: + - `size` : size in bytes + - `gid` : group ID + - `uid` : owner ID + - `ino` : inode number + - `nlink` : number of _hard_ links + - `ctime` : time of last change in Unix epoch format + - `atime` : last access time in Unix epoch format + - `mtime` : last modification time in Unix epoch format + - `mode` : file mode as a decimal number + - `modeoct` : file mode as an octal number, e.g. `10777` + - `permstr` : permission string, e.g. `-rwx---rwx` (not available on Windows) + - `permoct` : permissions as an octal number, e.g. `644` (not available on Windows) + - `type` : file type (not available on Windows): `block device`,`character device`, `directory`, `FIFO/pipe`, `symlink`, `regular file`, `socket`, or `unknown` + - `devno` : device number (drive letter on Windows, e.g. `C:`) + - `dev_minor` : minor device number (not available on Windows) + - `dev_major` : major device number (not available on Windows) + - `basename` : the file name minus the directory + - `dirname` : the directory portion of the file name + - `linktarget` : if the file is a `symlink`, its _final_ target. The target is chased up to 32 levels of recursion. On Windows, this returns the file name itself. + - `linktarget_shallow` : if the file is a `symlink`, its _first_ target. On Windows, this returns the file name itself. + - `xattr` : a string with newline-separated extended attributes and SELinux contexts in `key=valuekey2=value2tag1tag2` format. On Mac OS X, you can list and set extended attributes with the `xattr` utility. @@ -57,8 +57,8 @@ Output: **Notes:** -* `linktarget` will prepend the directory name to *relative symlink targets*, in order to be able to resolve them. Use `linktarget_shallow` to get the exact link as-is in case it is a relative link. -* The list of fields may be extended as needed by CFEngine. +- `linktarget` will prepend the directory name to _relative symlink targets_, in order to be able to resolve them. Use `linktarget_shallow` to get the exact link as-is in case it is a relative link. +- The list of fields may be extended as needed by CFEngine. **History:** diff --git a/content/reference/functions/filter.markdown b/content/reference/functions/filter.markdown index 65b492168..16de9c551 100644 --- a/content/reference/functions/filter.markdown +++ b/content/reference/functions/filter.markdown @@ -15,18 +15,18 @@ elements in `list` that match the filtering rules specified in `filter`, **Arguments**: -* filter : [Anchored][anchored] regular expression or static string to find, in the range `.*` -* list : The name of the list variable or data container to check, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` -* is_regex_ : Boolean +- filter : [Anchored][anchored] regular expression or static string to find, in the range `.*` +- list : The name of the list variable or data container to check, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` +- is*regex* : Boolean Treat `filter` as a regular expression or as a static string. -* `invert` : Boolean +- `invert` : Boolean Invert filter. -* `max_return` : Maximum number of elements to return in the range `0,999999999` +- `max_return` : Maximum number of elements to return in the range `0,999999999` **Example:** diff --git a/content/reference/functions/findfiles.markdown b/content/reference/functions/findfiles.markdown index 97eced76f..95853ec4d 100644 --- a/content/reference/functions/findfiles.markdown +++ b/content/reference/functions/findfiles.markdown @@ -11,17 +11,17 @@ This function searches for the given glob patterns in the local filesystem, returning files or directories that match. Note that glob patterns are not regular expressions. They match like Unix shells: -* `*` matches any filename or directory at one level, e.g. `*.cf` will -match all files in one directory that end in `.cf` but it won't search -across directories. `*/*.cf` on the other hand will look two levels -deep. -* `**` recursively matches up to six subdirectories. -* `?` matches a single letter. -* `[abc]` matches `a`, `b` or `c`. -* `[!abc]` matches any letters other than `a`, `b` or `c`. -* `[a-z]` matches any letter from `a` to `z`. -* `[!a-z]` matches any letter not from `a` to `z`. -* `{foo,bar}` matches `foo` or `bar`. +- `*` matches any filename or directory at one level, e.g. `*.cf` will + match all files in one directory that end in `.cf` but it won't search + across directories. `*/*.cf` on the other hand will look two levels + deep. +- `**` recursively matches up to six subdirectories. +- `?` matches a single letter. +- `[abc]` matches `a`, `b` or `c`. +- `[!abc]` matches any letters other than `a`, `b` or `c`. +- `[a-z]` matches any letter from `a` to `z`. +- `[!a-z]` matches any letter not from `a` to `z`. +- `{foo,bar}` matches `foo` or `bar`. This function, used together with the `bundlesmatching` function, allows you to do dynamic inputs and a dynamic bundle call chain. diff --git a/content/reference/functions/findfiles_up.markdown b/content/reference/functions/findfiles_up.markdown index 0ce04ccf0..2e908daf1 100644 --- a/content/reference/functions/findfiles_up.markdown +++ b/content/reference/functions/findfiles_up.markdown @@ -19,17 +19,17 @@ and last file or directory found respectively. Note that glob patterns are not regular expressions. They match like Unix shells: -* `*` matches any filename or directory at one level, e.g. `*.cf` will -match all files in one directory that end in `.cf` but it won't search -across directories. `*/*.cf` on the other hand will look two levels -deep. -* `**` recursively matches up to six subdirectories. -* `?` matches a single letter. -* `[abc]` matches `a`, `b` or `c`. -* `[!abc]` matches any letters other than `a`, `b` or `c`. -* `[a-z]` matches any letter from `a` to `z`. -* `[!a-z]` matches any letter not from `a` to `z`. -* `{foo,bar}` matches `foo` or `bar`. +- `*` matches any filename or directory at one level, e.g. `*.cf` will + match all files in one directory that end in `.cf` but it won't search + across directories. `*/*.cf` on the other hand will look two levels + deep. +- `**` recursively matches up to six subdirectories. +- `?` matches a single letter. +- `[abc]` matches `a`, `b` or `c`. +- `[!abc]` matches any letters other than `a`, `b` or `c`. +- `[a-z]` matches any letter from `a` to `z`. +- `[!a-z]` matches any letter not from `a` to `z`. +- `{foo,bar}` matches `foo` or `bar`. {{< CFEngine_function_attributes(path, glob, level) >}} diff --git a/content/reference/functions/findlocalusers.markdown b/content/reference/functions/findlocalusers.markdown index 43bda4319..5cbbff3a1 100644 --- a/content/reference/functions/findlocalusers.markdown +++ b/content/reference/functions/findlocalusers.markdown @@ -12,12 +12,13 @@ title: findlocalusers The `filter` argument can be used to look up users with specific attributes that match values. The filter is a `"data"` container or `"slist"` comprised of pairs of attribute and value/regex pattern `{ "attribute1=value1", "attribute2=value2", ... }`. The possible attributes are: -* `name`: name -* `uid`: user id -* `gid`: group id -* `gecos`: description -* `dir`: path to home directory -* `shell`: default shell + +- `name`: name +- `uid`: user id +- `gid`: group id +- `gecos`: description +- `dir`: path to home directory +- `shell`: default shell **Example:** @@ -29,8 +30,8 @@ Output: **Notes:** -* This function is currently only available on Unix-like systems. +- This function is currently only available on Unix-like systems. **History:** -* Function added in 3.26.0. +- Function added in 3.26.0. diff --git a/content/reference/functions/format.markdown b/content/reference/functions/format.markdown index c9a59a4f2..c1e6021f4 100644 --- a/content/reference/functions/format.markdown +++ b/content/reference/functions/format.markdown @@ -11,13 +11,13 @@ This function will format numbers (`o`, `x`, `d` and `f`) or strings (`s`) but not potentially dangerous things like individual characters or pointer offsets. -The `%S` specifier is special and non-standard. When you use it on a +The `%S` specifier is special and non-standard. When you use it on a slist or a data container, the data will be packed into a one-line string you can put in a log message, for instance. This function will fail if it doesn't have enough arguments; if any -format *specifier* contains the *modifiers* `hLqjzt`; or if any format -*specifier* is not one of `doxfsS`. +format _specifier_ contains the _modifiers_ `hLqjzt`; or if any format +_specifier_ is not one of `doxfsS`. **Example:** @@ -27,8 +27,8 @@ Output: {{< CFEngine_include_snippet(format.cf, #\+begin_src\s+example_output\s*, .*end_src) >}} -**Note:** the underlying `sprintf` system call may behave differently on some platforms for some formats. Test carefully. For example, the format `%08s` will use spaces to fill the string up to 8 characters on libc platforms, but on Darwin (Mac OS X) it will use zeroes. According to [SUSv4](http://pubs.opengroup.org/onlinepubs/9699919799/functions/sprintf.html) the behavior is undefined for this specific case. +**Note:** the underlying `sprintf` system call may behave differently on some platforms for some formats. Test carefully. For example, the format `%08s` will use spaces to fill the string up to 8 characters on libc platforms, but on Darwin (Mac OS X) it will use zeroes. According to [SUSv4](http://pubs.opengroup.org/onlinepubs/9699919799/functions/sprintf.html) the behavior is undefined for this specific case. **History:** -* Added in CFEngine 3.6.0 +- Added in CFEngine 3.6.0 diff --git a/content/reference/functions/getbundlemetatags.markdown b/content/reference/functions/getbundlemetatags.markdown index 42692542b..97a7fabcc 100644 --- a/content/reference/functions/getbundlemetatags.markdown +++ b/content/reference/functions/getbundlemetatags.markdown @@ -42,4 +42,4 @@ Output: **History:** -* Function added in 3.26.0. +- Function added in 3.26.0. diff --git a/content/reference/functions/getclassmetatags.markdown b/content/reference/functions/getclassmetatags.markdown index e14341b9a..dd48d339a 100644 --- a/content/reference/functions/getclassmetatags.markdown +++ b/content/reference/functions/getclassmetatags.markdown @@ -24,7 +24,7 @@ Output: **History:** -* Function added in 3.6.0. -* `optional_tag` added in 3.10.0 +- Function added in 3.6.0. +- `optional_tag` added in 3.10.0 **See also:** `getvariablemetatags()` diff --git a/content/reference/functions/getfields.markdown b/content/reference/functions/getfields.markdown index ce29725c5..ffdf89acc 100644 --- a/content/reference/functions/getfields.markdown +++ b/content/reference/functions/getfields.markdown @@ -9,26 +9,26 @@ title: getfields The function returns the number of lines matched. This function is most useful when you want only the first matching line (e.g., to mimic the -behavior of the *getpwnam(3)* on the file `/etc/passwd`). If you want to -examine *all* lines, use [readstringarray()][readstringarray] instead. +behavior of the _getpwnam(3)_ on the file `/etc/passwd`). If you want to +examine _all_ lines, use [readstringarray()][readstringarray] instead. **Arguments**: -* `regex` : Regular expression to match line, in the range `.*` +- `regex` : Regular expression to match line, in the range `.*` A regular expression matching one or more lines. The regular expression is [anchored][anchored], meaning it must match the entire line. -* `filename` : Filename to read, in the range `"?(/.*)` +- `filename` : Filename to read, in the range `"?(/.*)` The name of the file to be examined. -* `split` : Regular expression to split fields, in the range `.*` +- `split` : Regular expression to split fields, in the range `.*` A regex pattern that is used to parse the field separator(s) to split up the file into items -* `array_lval` : Return array name, in the range `.*` +- `array_lval` : Return array name, in the range `.*` The base name of the array that returns the values. @@ -42,7 +42,7 @@ Output: **Notes:** This function matches lines (using a regular expression) in the named -file, and splits the *first* matched line into fields (using a second +file, and splits the _first_ matched line into fields (using a second regular expression), placing these into a named array whose elements are `array[1],array[2],..`. This is useful for examining user data in the Unix password or group files. diff --git a/content/reference/functions/getusers.markdown b/content/reference/functions/getusers.markdown index ab0f0dfd5..4c3856f9a 100644 --- a/content/reference/functions/getusers.markdown +++ b/content/reference/functions/getusers.markdown @@ -19,11 +19,11 @@ title: getusers **Notes:** -* This function is currently only available on Unix-like systems. -* This function will return both local and remote (for example, users defined in an external directory like LDAP) users on a system. +- This function is currently only available on Unix-like systems. +- This function will return both local and remote (for example, users defined in an external directory like LDAP) users on a system. **History:** -* Introduced in CFEngine 3.1.0b1, CFEngine Nova/Enterprise 2.0.0b1 (2010). +- Introduced in CFEngine 3.1.0b1, CFEngine Nova/Enterprise 2.0.0b1 (2010). **See also:** [`getuserinfo()`][getuserinfo], [`users`][users]. diff --git a/content/reference/functions/getvalues.markdown b/content/reference/functions/getvalues.markdown index 5eca4e05c..24ce1718c 100644 --- a/content/reference/functions/getvalues.markdown +++ b/content/reference/functions/getvalues.markdown @@ -14,8 +14,8 @@ If the array contains list values, then all of the list elements are flattened into a single list to make the return value a list. If the data container contains non-scalar values (e.g. nested -containers) they are skipped. The special values `true`, `false`, and -`null` are serialized to their string representations. Numerical +containers) they are skipped. The special values `true`, `false`, and +`null` are serialized to their string representations. Numerical values are serialized to their string representations. You can specify a path inside the container. For example, below you'll diff --git a/content/reference/functions/getvariablemetatags.markdown b/content/reference/functions/getvariablemetatags.markdown index 252d3e44f..932ea44ee 100644 --- a/content/reference/functions/getvariablemetatags.markdown +++ b/content/reference/functions/getvariablemetatags.markdown @@ -31,5 +31,5 @@ Output: **History:** -* Introduced in CFEngine 3.6.0 -* `optional_tag` added in 3.10.0 +- Introduced in CFEngine 3.6.0 +- `optional_tag` added in 3.10.0 diff --git a/content/reference/functions/grep.markdown b/content/reference/functions/grep.markdown index 91722a457..cbc6da8fb 100644 --- a/content/reference/functions/grep.markdown +++ b/content/reference/functions/grep.markdown @@ -5,7 +5,7 @@ title: grep {{< CFEngine_function_prototype(regex, list) >}} -**Description:** Returns the sub-list if items in `list` matching the +**Description:** Returns the sub-list if items in `list` matching the [anchored][anchored] regular expression `regex`. [This function can accept many types of data parameters.][Functions#collecting functions] diff --git a/content/reference/functions/host2ip.markdown b/content/reference/functions/host2ip.markdown index fe93aafb6..c3675f4f7 100644 --- a/content/reference/functions/host2ip.markdown +++ b/content/reference/functions/host2ip.markdown @@ -26,7 +26,7 @@ bundle server control } ``` -**See also:** `ip2host()`, `isipinsubnet()`, `iprange()` +**See also:** `ip2host()`, `isipinsubnet()`, `iprange()` **History:** This function was introduced in CFEngine version 3.0.4 (2010) diff --git a/content/reference/functions/ifelse.markdown b/content/reference/functions/ifelse.markdown index ca284717c..446c994f0 100644 --- a/content/reference/functions/ifelse.markdown +++ b/content/reference/functions/ifelse.markdown @@ -48,7 +48,7 @@ class3.!class2:: ``` That's hard to read and error-prone (do you know how `class2` will -affect the default case?). Here's the alternative with `ifelse`: +affect the default case?). Here's the alternative with `ifelse`: ```cf3 "myvar" string => ifelse("class1.class2", "x", @@ -109,5 +109,5 @@ bundle agent example **History:** -* Special behavior actuating function with undefined variable references when 3 +- Special behavior actuating function with undefined variable references when 3 parameters are in use added in `3.7.4` and `3.9.1`. diff --git a/content/reference/functions/int.markdown b/content/reference/functions/int.markdown index 5e680acc7..d68aee673 100644 --- a/content/reference/functions/int.markdown +++ b/content/reference/functions/int.markdown @@ -9,7 +9,7 @@ title: int {{< CFEngine_function_attributes(string) >}} -If `string` represents a floating point number then the decimals are *truncated*. +If `string` represents a floating point number then the decimals are _truncated_. **Example:** @@ -19,4 +19,4 @@ If `string` represents a floating point number then the decimals are *truncated* **History:** -* Introduced in 3.18.0 +- Introduced in 3.18.0 diff --git a/content/reference/functions/irange.markdown b/content/reference/functions/irange.markdown index 4a849b4c2..33e481316 100644 --- a/content/reference/functions/irange.markdown +++ b/content/reference/functions/irange.markdown @@ -24,23 +24,23 @@ irange(ago(0,0,0,1,30,0), "0"); **See also:** -* Functions commonly used with [`irange()`][irange] - * [`ago()`][ago] - * [`now()`][now] - * [`accumulated()`][accumulated] -* Attributes of type ```irange``` - * [`atime` in body `file_select`][files#atime] - * [`copy_size` in body `copy_from`][files#copy_size] - * [`ctime` in body `file_select`][files#ctime] - * [`mtime` in body `file_select`][files#mtime] - * [`match_range` in body `process_count`][processes#match_range] - * [`pgid` in body `process_select`][processes#pgid] - * [`pid` in body `process_select`][processes#pid] - * [`ppid` in body `process_select`][processes#ppid] - * [`priority` in body `process_select`][processes#priority] - * [`rsize` in body `process_select`][processes#rsize] - * [`search_size` in body `file_select`][files#search_size] - * [`stime_range` in body `process_select`][processes#stime_range] - * [`threads` in body `process_select`][processes#threads] - * [`ttime_range` in body `process_select`][processes#ttime_range] - * [`vsize` in body `process_select`][processes#vsize] +- Functions commonly used with [`irange()`][irange] + - [`ago()`][ago] + - [`now()`][now] + - [`accumulated()`][accumulated] +- Attributes of type `irange` + - [`atime` in body `file_select`][files#atime] + - [`copy_size` in body `copy_from`][files#copy_size] + - [`ctime` in body `file_select`][files#ctime] + - [`mtime` in body `file_select`][files#mtime] + - [`match_range` in body `process_count`][processes#match_range] + - [`pgid` in body `process_select`][processes#pgid] + - [`pid` in body `process_select`][processes#pid] + - [`ppid` in body `process_select`][processes#ppid] + - [`priority` in body `process_select`][processes#priority] + - [`rsize` in body `process_select`][processes#rsize] + - [`search_size` in body `file_select`][files#search_size] + - [`stime_range` in body `process_select`][processes#stime_range] + - [`threads` in body `process_select`][processes#threads] + - [`ttime_range` in body `process_select`][processes#ttime_range] + - [`vsize` in body `process_select`][processes#vsize] diff --git a/content/reference/functions/is_type.markdown b/content/reference/functions/is_type.markdown index 7d90a6552..f6cfe9f9b 100644 --- a/content/reference/functions/is_type.markdown +++ b/content/reference/functions/is_type.markdown @@ -23,4 +23,4 @@ Output: **History:** -* Introduced in 3.26.0 +- Introduced in 3.26.0 diff --git a/content/reference/functions/isconnectable.markdown b/content/reference/functions/isconnectable.markdown index 2d26bae95..e239b93fc 100644 --- a/content/reference/functions/isconnectable.markdown +++ b/content/reference/functions/isconnectable.markdown @@ -17,4 +17,4 @@ This function checks whether a `hostname`:`port` is connectable within `timeout` **History:** -* Introduced in 3.26.0 +- Introduced in 3.26.0 diff --git a/content/reference/functions/isreadable.markdown b/content/reference/functions/isreadable.markdown index 53166a0fc..5b813c137 100644 --- a/content/reference/functions/isreadable.markdown +++ b/content/reference/functions/isreadable.markdown @@ -32,7 +32,7 @@ thread does not finish in time, the agent will consider the file unreadable. If the file is of size 0, the function will return true, if it successfully reads 0 bytes (reaches end-of-file). -Please *note* that the agent will evaluate this policy function multiple times, +Please _note_ that the agent will evaluate this policy function multiple times, meaning that the use of this function can cause a significant performance penalty. diff --git a/content/reference/functions/lsdir.markdown b/content/reference/functions/lsdir.markdown index 307006b87..d4f5ad81b 100644 --- a/content/reference/functions/lsdir.markdown +++ b/content/reference/functions/lsdir.markdown @@ -22,7 +22,7 @@ Output: **Tips:** -* Filter out the current (`.`) and parent (`..`) directories with a +- Filter out the current (`.`) and parent (`..`) directories with a negative look ahead. `lsdir( "/tmp", "^(?!(\.$|\.\.$)).*", false )`. **History:** Was introduced in 3.3.0, Nova 2.2.0 (2011) diff --git a/content/reference/functions/maparray.markdown b/content/reference/functions/maparray.markdown index d870f1669..045084b88 100644 --- a/content/reference/functions/maparray.markdown +++ b/content/reference/functions/maparray.markdown @@ -23,7 +23,7 @@ example below for an illustration. If a value in the array is an `slist`, you'll get one result for each value (implicit looping). -The order of the array keys is not guaranteed. Use the `sort` +The order of the array keys is not guaranteed. Use the `sort` function if you need order in the resulting output. {{< CFEngine_function_attributes(pattern, array_or_container) >}} diff --git a/content/reference/functions/mergedata.markdown b/content/reference/functions/mergedata.markdown index b99262d65..26ad2530c 100644 --- a/content/reference/functions/mergedata.markdown +++ b/content/reference/functions/mergedata.markdown @@ -28,7 +28,7 @@ traditional list and array data types in CFEngine. - Bare values try to expand a named CFEngine data container - It is only possible to wrap data containers in the current namespace. - true and false are reserved bare values -- In the event of key collision the *last* key merged wins +- In the event of key collision the _last_ key merged wins {{< CFEngine_function_attributes() >}} @@ -50,7 +50,7 @@ traditional list and array data types in CFEngine. **History:** -* Introduced in CFEngine 3.6.0 (2014). -* The [collecting function][Functions#collecting functions] behavior was added in 3.9. +- Introduced in CFEngine 3.6.0 (2014). +- The [collecting function][Functions#collecting functions] behavior was added in 3.9. **See also:** [`data_expand()`][data_expand], `getindices()`, `getvalues()`, `readjson()`, `parsejson()`, `readyaml()`, `parseyaml()`, [about collecting functions][Functions#collecting functions], and `data` documentation. diff --git a/content/reference/functions/network_connections.markdown b/content/reference/functions/network_connections.markdown index bb8777563..bfdb74ee5 100644 --- a/content/reference/functions/network_connections.markdown +++ b/content/reference/functions/network_connections.markdown @@ -11,10 +11,10 @@ title: network_connections The returned data container has four keys: -* `tcp` has all the TCP connections over IPv4 -* `tcp6` has all the TCP connections over IPv6 -* `udp` has all the UDP connections over IPv4 -* `udp6` has all the UDP connections over IPv6 +- `tcp` has all the TCP connections over IPv4 +- `tcp6` has all the TCP connections over IPv6 +- `udp` has all the UDP connections over IPv4 +- `udp6` has all the UDP connections over IPv6 Under each key, there's an array of connection objects that all look like this: diff --git a/content/reference/functions/not.markdown b/content/reference/functions/not.markdown index 619d80869..1a27aa609 100644 --- a/content/reference/functions/not.markdown +++ b/content/reference/functions/not.markdown @@ -12,7 +12,7 @@ any argument evaluates to true. **Argument Descriptions:** -* `expression` - Class, class expression, or function that returns a class +- `expression` - Class, class expression, or function that returns a class **Example:** @@ -28,5 +28,5 @@ commands: **History:** -* Introduced in 3.2.0, Nova 2.1.0 (2011) -* Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) +- Introduced in 3.2.0, Nova 2.1.0 (2011) +- Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) diff --git a/content/reference/functions/now.markdown b/content/reference/functions/now.markdown index 2b9beae15..6cdd8a968 100644 --- a/content/reference/functions/now.markdown +++ b/content/reference/functions/now.markdown @@ -47,7 +47,7 @@ R: Today is 2019-06-12 20:40:00 or in unix format '1560372000' R: 24 hours ago was 2019-06-11 20:40:00 or in unix format '1560372000' ``` -`files` type promises using ```file_select``` to limit recursive file selection +`files` type promises using `file_select` to limit recursive file selection based on a time relative to the agent start can make use of this function. ```cf3 @@ -72,14 +72,14 @@ body file_select pdf_modified_within_last_year } ``` -`processes` type promises using ```process_select``` can use this function to +`processes` type promises using `process_select` can use this function to select processes based on relative execution time. {{< CFEngine_include_example(processes_define_class_based_on_process_runtime.cf) >}} **See also:** -* Related functions - * [`ago()`][ago] - * [`accumulated()`][accumulated] - * [`irange()`][irange] +- Related functions + - [`ago()`][ago] + - [`accumulated()`][accumulated] + - [`irange()`][irange] diff --git a/content/reference/functions/nth.markdown b/content/reference/functions/nth.markdown index b3dbd0b48..9068a0089 100644 --- a/content/reference/functions/nth.markdown +++ b/content/reference/functions/nth.markdown @@ -12,11 +12,11 @@ requested, this function does not return a valid value. [This function can accept many types of data parameters.][Functions#collecting functions] -`list_or_container` can be an slist or a data container. If it's a -slist, the offset is simply the position in the list. If it's a data +`list_or_container` can be an slist or a data container. If it's a +slist, the offset is simply the position in the list. If it's a data container, the meaning of the `position_or_key` depends on its top-level contents: for a list like `[1,2,3,4]` you will get the list -element at `position_or_key`. For a key-value map like +element at `position_or_key`. For a key-value map like `{ a: 100, b: 200 }`, a `position_or_key` of `a` returns `100`. Since 3.15, Nth supports negative indices when indexing lists, starting from diff --git a/content/reference/functions/or.markdown b/content/reference/functions/or.markdown index 36356f0cb..2803a1cdf 100644 --- a/content/reference/functions/or.markdown +++ b/content/reference/functions/or.markdown @@ -27,5 +27,5 @@ commands: **History:** -* Introduced in 3.2.0, Nova 2.1.0 (2011) -* Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) +- Introduced in 3.2.0, Nova 2.1.0 (2011) +- Return type changed from `string` to `boolean` in 3.17.0 (2020) (CFE-3470) diff --git a/content/reference/functions/packagesmatching.markdown b/content/reference/functions/packagesmatching.markdown index 2d5dc9753..874d5e46e 100644 --- a/content/reference/functions/packagesmatching.markdown +++ b/content/reference/functions/packagesmatching.markdown @@ -45,9 +45,9 @@ some desired packages, and finally reports if they are installed. **Refresh rules:** -* installed packages cache used by packagesmatching() is refreshed at the end of each agent run in accordance with constraints defined in the relevant package module body. -* installed packages cache is refreshed after installing or removing a package. -* installed packages cache is refreshed if no local cache exists. +- installed packages cache used by packagesmatching() is refreshed at the end of each agent run in accordance with constraints defined in the relevant package module body. +- installed packages cache is refreshed after installing or removing a package. +- installed packages cache is refreshed if no local cache exists. This means a reliable way to force a refresh of CFEngine's internal package cache is to simply delete the local cache: @@ -63,8 +63,8 @@ $(sys.statedir)/software_packages.csv **History:** -* Introduced in CFEngine 3.6 -* Function started using `package_module` based data sources by default, even if +- Introduced in CFEngine 3.6 +- Function started using `package_module` based data sources by default, even if there is no `package_inventory` attribute defined in `body common control` if available in 3.23.0 diff --git a/content/reference/functions/packageupdatesmatching.markdown b/content/reference/functions/packageupdatesmatching.markdown index 8be6e6d60..f9b83c66d 100644 --- a/content/reference/functions/packageupdatesmatching.markdown +++ b/content/reference/functions/packageupdatesmatching.markdown @@ -49,9 +49,9 @@ vars: **Refresh rules:** -* updates cache used by packageupdatesmatching() is refreshed at the end of each agent run in accordance with constraints defined in the relevant package module body. -* updates cache is refreshed every time `repo` type package is installed or removed -* updates cache is refreshed if no local cache exists. +- updates cache used by packageupdatesmatching() is refreshed at the end of each agent run in accordance with constraints defined in the relevant package module body. +- updates cache is refreshed every time `repo` type package is installed or removed +- updates cache is refreshed if no local cache exists. This means a reliable way to force a refresh of CFEngine's internal package cache is to simply delete the local cache: @@ -67,8 +67,8 @@ $(sys.statedir)/software_patches_avail.csv **History:** -* Introduced in CFEngine 3.6 -* Function started using `package_module` based data sources by default, even if +- Introduced in CFEngine 3.6 +- Function started using `package_module` based data sources by default, even if there is no `package_inventory` attribute defined in `body common control` if available in 3.23.0 diff --git a/content/reference/functions/parseintarray.markdown b/content/reference/functions/parseintarray.markdown index c55b3ef96..d3dcd2be2 100644 --- a/content/reference/functions/parseintarray.markdown +++ b/content/reference/functions/parseintarray.markdown @@ -20,13 +20,13 @@ split into fields. Using the empty string (`""`) indicates no comments. **Arguments**: -* `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` -* `input` : A string to parse for input data, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split data, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` +- `input` : A string to parse for input data, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split data, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** @@ -36,6 +36,6 @@ Output: {{< CFEngine_include_snippet(parseintarray.cf, #\+begin_src\s+example_output\s*, .*end_src) >}} -**History:** Was introduced in version 3.1.5a1, Nova 2.1.0 (2011** +**History:** Was introduced in version 3.1.5a1, Nova 2.1.0 (2011\*\* **See also:** [`parsestringarray()`][parsestringarray], [`parserealarray()`][parserealarray], [`readstringarray()`][readstringarray], [`readintarray()`][readintarray], [`readrealarray()`][readrealarray] diff --git a/content/reference/functions/parsejson.markdown b/content/reference/functions/parsejson.markdown index 612f72857..27fcb2da6 100644 --- a/content/reference/functions/parsejson.markdown +++ b/content/reference/functions/parsejson.markdown @@ -33,11 +33,11 @@ vars: **Notes:** -* This functions does not parse _primitives_. +- This functions does not parse _primitives_. **History:** -* Introduced in CFEngine 3.6.0 -* The [collecting function][Functions#collecting functions] behavior was added in 3.9. +- Introduced in CFEngine 3.6.0 +- The [collecting function][Functions#collecting functions] behavior was added in 3.9. **See also:** `readjson()`, `parseyaml()`, `readyaml()`, `mergedata()`, `Inline YAML and JSON data`, [about collecting functions][Functions#collecting functions], and `data` documentation. diff --git a/content/reference/functions/parserealarray.markdown b/content/reference/functions/parserealarray.markdown index f576b4567..b7edf5088 100644 --- a/content/reference/functions/parserealarray.markdown +++ b/content/reference/functions/parserealarray.markdown @@ -21,13 +21,13 @@ split into fields. Using the empty string (`""`) indicates no comments. **Arguments**: -* `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` -* `input` : A string to parse for input data, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split data, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` +- `input` : A string to parse for input data, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split data, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** diff --git a/content/reference/functions/parsestringarray.markdown b/content/reference/functions/parsestringarray.markdown index 564e9730c..e218b6725 100644 --- a/content/reference/functions/parsestringarray.markdown +++ b/content/reference/functions/parsestringarray.markdown @@ -21,13 +21,13 @@ split into fields. Using the empty string (`""`) indicates no comments. **Arguments**: -* `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` -* `input` : A string to parse for input data, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split data, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range `[a-zA-Z0-9_$(){}\[\].:]+` +- `input` : A string to parse for input data, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split data, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** diff --git a/content/reference/functions/peerleaders.markdown b/content/reference/functions/peerleaders.markdown index 476775629..fdf24c0c5 100644 --- a/content/reference/functions/peerleaders.markdown +++ b/content/reference/functions/peerleaders.markdown @@ -25,7 +25,7 @@ e The peer leaders will be `a` and `c`. -The current host name does not need to belong to this file. If it's +The current host name does not need to belong to this file. If it's found (fully qualified or unqualified), the string `localhost` is used instead of the host name. diff --git a/content/reference/functions/randomint.markdown b/content/reference/functions/randomint.markdown index 75e4e41c2..9608605d3 100644 --- a/content/reference/functions/randomint.markdown +++ b/content/reference/functions/randomint.markdown @@ -5,12 +5,12 @@ title: randomint {{< CFEngine_function_prototype(lower, upper) >}} -**Description:** Returns a random integer between `lower` and *up to but not including* `upper`. +**Description:** Returns a random integer between `lower` and _up to but not including_ `upper`. The limits must be integer values and the resulting numbers are based on the entropy of the md5 algorithm. -The `upper` limit is excluded from the range. Thus `randomint(0, 100)` +The `upper` limit is excluded from the range. Thus `randomint(0, 100)` will return 100 possible values, not 101. The function will be re-evaluated on each pass if it is not restricted with a diff --git a/content/reference/functions/readfile.markdown b/content/reference/functions/readfile.markdown index 9f5817c73..eabf22955 100644 --- a/content/reference/functions/readfile.markdown +++ b/content/reference/functions/readfile.markdown @@ -28,12 +28,12 @@ Output: **Notes:** -* On Windows, the file will be read in text mode, which means that -CRLF line endings will be converted to LF line endings in the -resulting variable. This can make the variable length shorter than the -size of the file being read. +- On Windows, the file will be read in text mode, which means that + CRLF line endings will be converted to LF line endings in the + resulting variable. This can make the variable length shorter than the + size of the file being read. **History:** -* Warnings about the size limit and the special `0` value were introduced in 3.6.0 -* 4095 bytes limitation removed in 3.6.3 +- Warnings about the size limit and the special `0` value were introduced in 3.6.0 +- 4095 bytes limitation removed in 3.6.3 diff --git a/content/reference/functions/readintarray.markdown b/content/reference/functions/readintarray.markdown index 4113a640e..6e706a3b7 100644 --- a/content/reference/functions/readintarray.markdown +++ b/content/reference/functions/readintarray.markdown @@ -23,14 +23,14 @@ lines matched. **Arguments**: -* `array` : Array identifier to populate, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` -* `filename` : File name to read, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` +- `filename` : File name to read, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** diff --git a/content/reference/functions/readjson.markdown b/content/reference/functions/readjson.markdown index 4650b9dfe..213a5023c 100644 --- a/content/reference/functions/readjson.markdown +++ b/content/reference/functions/readjson.markdown @@ -25,4 +25,4 @@ vars: **History:** -* Introduced in CFEngine 3.6.0 +- Introduced in CFEngine 3.6.0 diff --git a/content/reference/functions/readrealarray.markdown b/content/reference/functions/readrealarray.markdown index 851eb8d82..40e0351a6 100644 --- a/content/reference/functions/readrealarray.markdown +++ b/content/reference/functions/readrealarray.markdown @@ -23,14 +23,14 @@ lines matched. **Arguments**: -* `array` : Array identifier to populate, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` -* `filename` : File name to read, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` +- `filename` : File name to read, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** @@ -110,6 +110,7 @@ array_name[games][5] /var/games array_name[games][6] /bin/bash ... ``` + Prepare: {{< CFEngine_include_snippet(readrealarray.cf, #\+begin_src prep, .*end_src) >}} diff --git a/content/reference/functions/readreallist.markdown b/content/reference/functions/readreallist.markdown index 213861efb..c73d06d98 100644 --- a/content/reference/functions/readreallist.markdown +++ b/content/reference/functions/readreallist.markdown @@ -16,12 +16,12 @@ split into fields. Using the empty string (`""`) indicates no comments. **Arguments**: -* `filename` : File name to read, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split data, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `filename` : File name to read, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split data, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** diff --git a/content/reference/functions/readstringarray.markdown b/content/reference/functions/readstringarray.markdown index c85ee6ffe..9624d3585 100644 --- a/content/reference/functions/readstringarray.markdown +++ b/content/reference/functions/readstringarray.markdown @@ -23,14 +23,14 @@ lines matched. **Arguments**: -* `array` : Array identifier to populate, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` -* `filename` : File name to read, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `array` : Array identifier to populate, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` +- `filename` : File name to read, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split lines into fields, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** @@ -110,6 +110,7 @@ array_name[games][5] /var/games array_name[games][6] /bin/bash ... ``` + Prepare: {{< CFEngine_include_snippet(readrealarray.cf, #\+begin_src prep, .*end_src) >}} diff --git a/content/reference/functions/readstringarrayidx.markdown b/content/reference/functions/readstringarrayidx.markdown index cbf2b3a2f..dfe7128f3 100644 --- a/content/reference/functions/readstringarrayidx.markdown +++ b/content/reference/functions/readstringarrayidx.markdown @@ -19,7 +19,7 @@ split into fields. Using the empty string (`""`) indicates no comments. Returns an integer number of keys in the array (i.e., the number of lines matched). If you only want the fields in the first matching line (e.g., to -mimic the behavior of the *getpwnam(3)* on the file `/etc/passwd`), use +mimic the behavior of the _getpwnam(3)_ on the file `/etc/passwd`), use `getfields()`, instead. {{< CFEngine_function_attributes(array, filename, comment, split, maxentries, maxbytes) >}} diff --git a/content/reference/functions/readstringlist.markdown b/content/reference/functions/readstringlist.markdown index bd6634d9f..65705e719 100644 --- a/content/reference/functions/readstringlist.markdown +++ b/content/reference/functions/readstringlist.markdown @@ -16,12 +16,12 @@ split into fields. Using the empty string (`""`) indicates no comments. **Arguments**: -* `filename` : File name to read, in the range `"?(/.*)` -* `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` -* `split` : [Unanchored][unanchored] regex to split data, in the range `.*` -* `maxentries` : Maximum number of entries to read, in the range -`0,99999999999` -* `maxbytes` : Maximum bytes to read, in the range `0,99999999999` +- `filename` : File name to read, in the range `"?(/.*)` +- `comment` : [Unanchored][unanchored] regex matching comments, in the range `.*` +- `split` : [Unanchored][unanchored] regex to split data, in the range `.*` +- `maxentries` : Maximum number of entries to read, in the range + `0,99999999999` +- `maxbytes` : Maximum bytes to read, in the range `0,99999999999` **Example:** diff --git a/content/reference/functions/readtcp.markdown b/content/reference/functions/readtcp.markdown index c55e0b0ef..530f5fc7e 100644 --- a/content/reference/functions/readtcp.markdown +++ b/content/reference/functions/readtcp.markdown @@ -5,7 +5,7 @@ title: readtcp {{< CFEngine_function_prototype(hostnameip, port, sendstring, maxbytes) >}} -**Description:** Connects to tcp ```port``` of `hostnameip`, sends `sendstring`, +**Description:** Connects to tcp `port` of `hostnameip`, sends `sendstring`, reads at most `maxbytes` from the response and returns those. If the send string is empty, no data are sent or received from the diff --git a/content/reference/functions/regex_replace.markdown b/content/reference/functions/regex_replace.markdown index db6d2db12..7a2c6e188 100644 --- a/content/reference/functions/regex_replace.markdown +++ b/content/reference/functions/regex_replace.markdown @@ -14,13 +14,13 @@ string in any order. Consult http://pcre.org/pcre.txt for the exact meaning of the uppercase options, and note that some can be turned on inside the regular expression, e.g. `(?s)`. -* `g`: global, replace all matches -* `i`: case-insensitive -* `m`: multiline (`PCRE_MULTILINE`) -* `s`: dot matches newlines too (`PCRE_DOTALL`) -* `x`: extended regular expressions (`PCRE_EXTENDED`, very nice for readability) -* `U`: ungreedy (`PCRE_UNGREEDY`) -* `T`: disables special characters and backreferences in the replacement string +- `g`: global, replace all matches +- `i`: case-insensitive +- `m`: multiline (`PCRE_MULTILINE`) +- `s`: dot matches newlines too (`PCRE_DOTALL`) +- `x`: extended regular expressions (`PCRE_EXTENDED`, very nice for readability) +- `U`: ungreedy (`PCRE_UNGREEDY`) +- `T`: disables special characters and backreferences in the replacement string In the replacement, `$1` and `\1` refer to the first capture group. `$2` and `\2` refer to the second, and so on, except there is no `\10` diff --git a/content/reference/functions/remoteclassesmatching.markdown b/content/reference/functions/remoteclassesmatching.markdown index acea7313e..b62614638 100644 --- a/content/reference/functions/remoteclassesmatching.markdown +++ b/content/reference/functions/remoteclassesmatching.markdown @@ -15,7 +15,7 @@ The return value is true (sets the class) if communication with the server was successful and classes were populated in the current bundle. This function contacts a remote `cf-serverd` and requests access to defined -*persistent classes* on that system. Access must be granted by making an +_persistent classes_ on that system. Access must be granted by making an `access` promise with `resource_type` set to `context`. {{< CFEngine_function_attributes(regex, server, encrypt, prefix) >}} diff --git a/content/reference/functions/remotescalar.markdown b/content/reference/functions/remotescalar.markdown index 02db0e987..06ff4094c 100644 --- a/content/reference/functions/remotescalar.markdown +++ b/content/reference/functions/remotescalar.markdown @@ -8,7 +8,7 @@ title: remotescalar {{< CFEngine_function_prototype(id, server, encrypt) >}} **Description:** Returns a scalar value identified by `id` from a remote CFEngine -`server`. Communication is encrytped depending on ```encrypt```. +`server`. Communication is encrytped depending on `encrypt`. If the identifier matches a persistent scalar variable then this will be returned preferentially. If no such variable is found, then the server will look for a diff --git a/content/reference/functions/returnszero.markdown b/content/reference/functions/returnszero.markdown index 9a9cdf88f..4657d73d1 100644 --- a/content/reference/functions/returnszero.markdown +++ b/content/reference/functions/returnszero.markdown @@ -27,9 +27,9 @@ operation is beyond CFEngine's ability to guarantee convergence, and on multiple passes and during syntax verification these function calls are executed, resulting in system changes that are **covert**. Calls to `execresult` should be for discovery and information extraction -only. Effectively calls to this function will be also repeatedly +only. Effectively calls to this function will be also repeatedly executed by `cf-promises` when it does syntax checking, which is -highly undesirable if the command is expensive. Consider using +highly undesirable if the command is expensive. Consider using `commands` promises instead, which have locking and are not evaluated by `cf-promises`. diff --git a/content/reference/functions/reverse.markdown b/content/reference/functions/reverse.markdown index a8705f73f..949ef5593 100644 --- a/content/reference/functions/reverse.markdown +++ b/content/reference/functions/reverse.markdown @@ -13,8 +13,8 @@ This is a simple function to reverse a list. **Arguments**: -* list : The name of the list variable to check, in the range -`[a-zA-Z0-9_$(){}\[\].:]+` +- list : The name of the list variable to check, in the range + `[a-zA-Z0-9_$(){}\[\].:]+` **Example:** diff --git a/content/reference/functions/selectservers.markdown b/content/reference/functions/selectservers.markdown index 377459ee4..ffb73118a 100644 --- a/content/reference/functions/selectservers.markdown +++ b/content/reference/functions/selectservers.markdown @@ -6,7 +6,7 @@ title: selectservers {{< CFEngine_function_prototype(hostlist, port, query, regex, maxbytes, array) >}} **Description:** Returns the number of tcp servers from `hostlist` which -respond with a reply matching `regex` to a `query` send to ```port```, and +respond with a reply matching `regex` to a `query` send to `port`, and populates `array` with their names. The regular expression is [anchored][anchored]. If `query` is empty, then no diff --git a/content/reference/functions/sort.markdown b/content/reference/functions/sort.markdown index cfb0b5bc1..daec61616 100644 --- a/content/reference/functions/sort.markdown +++ b/content/reference/functions/sort.markdown @@ -10,7 +10,7 @@ title: sort [This function can accept many types of data parameters.][Functions#collecting functions] Lexicographical, integer, real, IP, and MAC address sorting is -supported currently. The example below will show each sorting mode in +supported currently. The example below will show each sorting mode in action. `mode` is optional, and defaults to `lex`. Note IPv6 addresses can not use uppercase hexadecimal characters @@ -38,8 +38,9 @@ Output: ``` **History:** - - Function added in 3.6.0. - - [Collecting function][Functions#collecting functions] behavior added in 3.9.0. - - Optional `mode` defaulting to `lex` behavior added in 3.9.0. + +- Function added in 3.6.0. +- [Collecting function][Functions#collecting functions] behavior added in 3.9.0. +- Optional `mode` defaulting to `lex` behavior added in 3.9.0. **See also:** `shuffle()`, [about collecting functions][Functions#collecting functions], and `data` documentation. diff --git a/content/reference/functions/splayclass.markdown b/content/reference/functions/splayclass.markdown index f895df198..95fb8f828 100644 --- a/content/reference/functions/splayclass.markdown +++ b/content/reference/functions/splayclass.markdown @@ -6,14 +6,14 @@ title: splayclass {{< CFEngine_function_prototype(input, policy) >}} **Description:** Returns whether `input`'s time-slot has arrived, -according to a ```policy```. +according to a `policy`. The function returns true if the system clock lies within a scheduled time-interval that maps to a hash of `input` (which may be any arbitrary string). Different strings will hash to different time intervals, and thus one can map different tasks to time-intervals. -This function may be used to distribute a task, typically on multiple hosts, in time over a day or an hourly period, depending on the ```policy``` (that must be either `daily` or `hourly`). This is useful for copying resources to multiple hosts from a single server, (e.g. large software updates), when simultaneous scheduling would lead to a bottleneck and/or server overload. +This function may be used to distribute a task, typically on multiple hosts, in time over a day or an hourly period, depending on the `policy` (that must be either `daily` or `hourly`). This is useful for copying resources to multiple hosts from a single server, (e.g. large software updates), when simultaneous scheduling would lead to a bottleneck and/or server overload. The function is similar to the `splaytime` feature in `cf-execd`, except that it allows you to base the decision on any string-criterion on a given host. @@ -26,14 +26,14 @@ different times. Thus tasks could be scheduled according to group names for predictability, or according to IP addresses for distribution across the policy interval. -The times at which the `splayclass` will be defined depends on the ```policy```. +The times at which the `splayclass` will be defined depends on the `policy`. If it is `hourly` then the class will be defined for a 5-minute interval every hour. If the policy `daily`, then the class will be defined for one 5-minute interval every day. This means that `splayclass` assumes that you are running CFEngine with the default schedule of "every 5 minutes". If you change the executor `schedule` control variable, you may prevent the `splayclass` from ever being defined (that is, if the hashed 5-minute interval that is selected -by the `splayclass` is a time when you have told CFEngine *not* to run). +by the `splayclass` is a time when you have told CFEngine _not_ to run). **Example:** diff --git a/content/reference/functions/splitstring.markdown b/content/reference/functions/splitstring.markdown index edbcd1c86..68c9946b1 100644 --- a/content/reference/functions/splitstring.markdown +++ b/content/reference/functions/splitstring.markdown @@ -6,7 +6,7 @@ title: splitstring {{< CFEngine_function_prototype(string, regex, maxent) >}} **Description:** Splits `string` into at most `maxent` substrings wherever -`regex` occurs, and returns the list with those strings. +`regex` occurs, and returns the list with those strings. The regular expression is [unanchored][unanchored]. diff --git a/content/reference/functions/storejson.markdown b/content/reference/functions/storejson.markdown index e11f7029b..1b8d769d8 100644 --- a/content/reference/functions/storejson.markdown +++ b/content/reference/functions/storejson.markdown @@ -17,7 +17,7 @@ title: storejson **History:** -* Introduced in CFEngine 3.6.0 -* The [collecting function][Functions#collecting functions] behavior was added in 3.9. +- Introduced in CFEngine 3.6.0 +- The [collecting function][Functions#collecting functions] behavior was added in 3.9. **See also:** `readjson()`, `readyaml()`, `parsejson()`, `parseyaml()`, [about collecting functions][Functions#collecting functions], and `data` documentation. diff --git a/content/reference/functions/string.markdown b/content/reference/functions/string.markdown index c3aa3549e..6ffac96b8 100644 --- a/content/reference/functions/string.markdown +++ b/content/reference/functions/string.markdown @@ -11,7 +11,7 @@ title: string If `arg` is a container reference it will be serialized to a string. The reference must be indicated with `@(some_container)`. -Strings are *not* interpreted as references. +Strings are _not_ interpreted as references. **Example:** @@ -21,4 +21,4 @@ Strings are *not* interpreted as references. **History:** -* Introduced in 3.18.0 +- Introduced in 3.18.0 diff --git a/content/reference/functions/string_split.markdown b/content/reference/functions/string_split.markdown index 367e9e659..332f7d95f 100644 --- a/content/reference/functions/string_split.markdown +++ b/content/reference/functions/string_split.markdown @@ -6,14 +6,14 @@ title: string_split {{< CFEngine_function_prototype(string, regex, maxent) >}} **Description:** Splits `string` into at most `maxent` substrings wherever -`regex` occurs, and returns the list with those strings. +`regex` occurs, and returns the list with those strings. The regular expression is [unanchored][unanchored]. If the maximum number of substrings is insufficient to accommodate all the entries, the generated `slist` will have `maxent` items and the last one will contain the rest of the string starting with the -`maxent-1`-th delimiter. This is standard behavior in many languages +`maxent-1`-th delimiter. This is standard behavior in many languages like Perl or Ruby, and different from the `splitstring()` behavior. {{< CFEngine_function_attributes(string, regex, maxent) >}} diff --git a/content/reference/functions/type.markdown b/content/reference/functions/type.markdown index dbbc75455..472caf405 100644 --- a/content/reference/functions/type.markdown +++ b/content/reference/functions/type.markdown @@ -25,7 +25,7 @@ The following table demonstrates the strings you can expect to be returned with different combinations of the arguments `type` and `detail`. | type | detail | return | -|--------------|--------|---------------| +| ------------ | ------ | ------------- | | string | false | string | | string | true | policy string | | int | false | int | @@ -65,6 +65,6 @@ Output: **History:** -* Introduced in 3.18.0 +- Introduced in 3.18.0 **See also:** `is_type()`. diff --git a/content/reference/functions/url_get.markdown b/content/reference/functions/url_get.markdown index 066e70ea1..04914c3bb 100644 --- a/content/reference/functions/url_get.markdown +++ b/content/reference/functions/url_get.markdown @@ -6,8 +6,8 @@ title: url_get {{< CFEngine_function_prototype(url, options_container) >}} **Description:** Retrieves the contents of a `url` using options from - a data container. The data is returned in a - data container. +a data container. The data is returned in a +data container. **NOTE** that the `options_container` can be specified as inline JSON @@ -29,22 +29,22 @@ always provided. The available options currently are: -* `url.max_content`: if present, specifies the maximum number of content bytes to retrieve ( **default 4096** ). -* `url.max_headers`: if present, specifies the maximum number of response headers to retrieve ( **default 4096** ). -* `url.verbose`: if 1, `libcurl` will be more verbose while retrieving the content ( **default 0** ). -* `url.timeout`: if present, `libcurl` will time out the request after that many seconds ( **default 3** ). -* `url.referer`: if present, `libcurl` will set the Referer to this ( **default unset** ). -* `url.user-agent`: if present, `libcurl` will set the User-Agent to this ( **default unset** ). -* `url.headers`: an array of strings in the format `Foo: bar` specifying headers for the request ( **default `[Host: host , Accept: \*/\*]`** ). +- `url.max_content`: if present, specifies the maximum number of content bytes to retrieve ( **default 4096** ). +- `url.max_headers`: if present, specifies the maximum number of response headers to retrieve ( **default 4096** ). +- `url.verbose`: if 1, `libcurl` will be more verbose while retrieving the content ( **default 0** ). +- `url.timeout`: if present, `libcurl` will time out the request after that many seconds ( **default 3** ). +- `url.referer`: if present, `libcurl` will set the Referer to this ( **default unset** ). +- `url.user-agent`: if present, `libcurl` will set the User-Agent to this ( **default unset** ). +- `url.headers`: an array of strings in the format `Foo: bar` specifying headers for the request ( **default `[Host: host , Accept: \*/\*]`** ). The returned data container will have the following keys: -* `returncode`: the HTTP response code, e.g. `200`. -* `rc`: the `libcurl` integer result code, either `0` for success or something else for failure -* `error_message`: when present, indicates the request was unsuccessful and explains why -* `success`: a boolean. When `success` is `false`, the result code was not `0` and the request was unsuccessful. -* `content`: the response content as a string -* `headers`: the response headers as a string +- `returncode`: the HTTP response code, e.g. `200`. +- `rc`: the `libcurl` integer result code, either `0` for success or something else for failure +- `error_message`: when present, indicates the request was unsuccessful and explains why +- `success`: a boolean. When `success` is `false`, the result code was not `0` and the request was unsuccessful. +- `content`: the response content as a string +- `headers`: the response headers as a string {{< CFEngine_function_attributes(url, options_container) >}} diff --git a/content/reference/functions/usemodule.markdown b/content/reference/functions/usemodule.markdown index cd1502c95..927822e55 100644 --- a/content/reference/functions/usemodule.markdown +++ b/content/reference/functions/usemodule.markdown @@ -29,4 +29,5 @@ bundle agent test "/bin/echo" args => "test $(user)"; } ``` + **See also:** [read_module_protocol()][read_module_protocol], [Module Protocol][commands#module] diff --git a/content/reference/functions/variablesmatching.markdown b/content/reference/functions/variablesmatching.markdown index a9927d645..55911a878 100644 --- a/content/reference/functions/variablesmatching.markdown +++ b/content/reference/functions/variablesmatching.markdown @@ -15,7 +15,7 @@ variables. When one or more tags are given, the variables with tags matching any of the given [anchored][anchored] regular expressions are returned (logical OR semantics). For example, if one variable has tag `inventory`, a second variable has tag `time_based` -but not `inventory`, *both* are returned by variablesmatching(".*", "inventory", "time_based"). +but not `inventory`, _both_ are returned by variablesmatching(".\*", "inventory", "time_based"). If you want logical AND semantics instead, you can make two calls to the function with one tag in each call and use the `intersection` function on the return values. diff --git a/content/reference/functions/variablesmatching_as_data.markdown b/content/reference/functions/variablesmatching_as_data.markdown index 3b7458dff..8b6cfcc8f 100644 --- a/content/reference/functions/variablesmatching_as_data.markdown +++ b/content/reference/functions/variablesmatching_as_data.markdown @@ -16,7 +16,7 @@ variables. When one or more tags are given, the variables with tags matching any of the given [anchored][anchored] regular expressions are returned (logical OR semantics). For example, if one variable has tag `inventory`, a second variable has tag `time_based` -but not `inventory`, *both* are returned by variablesmatching_as_data(".*", "inventory", "time_based"). +but not `inventory`, _both_ are returned by variablesmatching_as_data(".\*", "inventory", "time_based"). If you want logical AND semantics instead, you can make two calls to the function with one tag in each call and use the `intersection` function on the return values. diff --git a/content/reference/functions/version_compare.markdown b/content/reference/functions/version_compare.markdown index 85802017d..3b0e451f7 100644 --- a/content/reference/functions/version_compare.markdown +++ b/content/reference/functions/version_compare.markdown @@ -79,4 +79,4 @@ Thus, it is often more intuitive to use the `>=` operator to mean all versions a **History:** -* Introduced in 3.23.0 +- Introduced in 3.23.0 diff --git a/content/reference/language-concepts/_index.markdown b/content/reference/language-concepts/_index.markdown index 73ea48ace..6dfa5f9fe 100644 --- a/content/reference/language-concepts/_index.markdown +++ b/content/reference/language-concepts/_index.markdown @@ -22,7 +22,7 @@ promise_type: } ``` -In addition, CFEngine bodies can be defined and used as attribute values. Here's a real-life example of a body and its usage. +In addition, CFEngine bodies can be defined and used as attribute values. Here's a real-life example of a body and its usage. ```cf3 body edit_defaults no_backup @@ -36,68 +36,68 @@ body edit_defaults no_backup "myfile" edit_defaults => no_backup; ``` -You can recognize *everything* in CFEngine from just those few concepts. +You can recognize _everything_ in CFEngine from just those few concepts. -* [**Promise**][promises] +- [**Promise**][promises] -A declaration about the *state* we desire to maintain (e.g., the permissions +A declaration about the _state_ we desire to maintain (e.g., the permissions or contents of a file, the availability or absence of a service, the (de)installation of a package). -* [**Bundles**][bundles] +- [**Bundles**][bundles] A collection of promises. -* [**Bodies**][bodies] +- [**Bodies**][bodies] A part of a promise which details and constrains its nature, possibly in -separate and re-usable parts. Effectively a body is like a promise attribute that has several parameters. +separate and re-usable parts. Effectively a body is like a promise attribute that has several parameters. -* [**Classes**][classes and decisions] +- [**Classes**][classes and decisions] CFEngine's boolean classifiers that describe context. -* [**Variables and datatypes**][variables] +- [**Variables and datatypes**][variables] -An association of the form "LVALUE *represents* RVALUE", where RVALUE may be a +An association of the form "LVALUE _represents_ RVALUE", where RVALUE may be a scalar value or a list of scalar values: a string, integer or real number. This documentation about the language concepts introduces: -* Policy evaluation (also known as [**Normal order**][Policy evaluation]) -* [**loops**][Loops] and implicit iteration -* [**pattern matching and referencing**][Pattern matching and referencing] -* [**namespaces**][namespaces] +- Policy evaluation (also known as [**Normal order**][Policy evaluation]) +- [**loops**][Loops] and implicit iteration +- [**pattern matching and referencing**][Pattern matching and referencing] +- [**namespaces**][namespaces] ## Syntax, identifiers and names The CFEngine 3 language has a few simple rules: -* CFEngine built-in words, names of variables, bundles, body templates and classes may only contain the usual alphanumeric and underscore characters (`a-zA-Z0-9_`) -* All other 'literal' data must be quoted. -* Declarations of promise bundles in the form: +- CFEngine built-in words, names of variables, bundles, body templates and classes may only contain the usual alphanumeric and underscore characters (`a-zA-Z0-9_`) +- All other 'literal' data must be quoted. +- Declarations of promise bundles in the form: bundle agent-type identifier { ... } - where `agent-type` is the CFEngine component responsible for maintaining the promise. + where `agent-type` is the CFEngine component responsible for maintaining the promise. -* Declarations of promise body-parts in the form: +- Declarations of promise body-parts in the form: body constraint_type template_identifier { ... } - matching and expanding on a reference inside a promise of the form `constraint_type => template_identifier` + matching and expanding on a reference inside a promise of the form `constraint_type => template_identifier` -* attribute expressions in the body of a promise take the form +- attribute expressions in the body of a promise take the form left-hand-side (CFEngine_word) => right-hand-side (user defined data). - This can take several forms: + This can take several forms: cfengine_word => user_defined_template(parameters) user_defined_template @@ -105,17 +105,17 @@ The CFEngine 3 language has a few simple rules: "quoted literal scalar" { list } - In each of these cases, the right hand side is a user choice. + In each of these cases, the right hand side is a user choice. - CFEngine uses many _constraint expressions_ as part of the body of a promise. These take the form: left-hand-side (CFEngine word) '=>' right-hand-side (user defined data). This can take several forms: + CFEngine uses many _constraint expressions_ as part of the body of a promise. These take the form: left-hand-side (CFEngine word) '=>' right-hand-side (user defined data). This can take several forms: - cfengine_word => user_defined_template(parameters) - user_defined_template - builtin_function() - "quoted literal scalar" - { list } + cfengine_word => user_defined_template(parameters) + user_defined_template + builtin_function() + "quoted literal scalar" + { list } - In each of these cases, the right hand side is a user choice. + In each of these cases, the right hand side is a user choice. ## Filenames and paths diff --git a/content/reference/language-concepts/augments.markdown b/content/reference/language-concepts/augments.markdown index 558a183b8..12a12bf65 100644 --- a/content/reference/language-concepts/augments.markdown +++ b/content/reference/language-concepts/augments.markdown @@ -55,7 +55,7 @@ as specified by the [_augments_ key][Augments#augments]. **Notes:** -* CFEngine variables are **not** expanded unless otherwise noted. +- CFEngine variables are **not** expanded unless otherwise noted. ### host_specific.json @@ -64,21 +64,21 @@ are automatically tagged with `source=cmdb`. Variables defined from this file ca **Notes:** -* This file does not support the [_augments_ key][Augments#augments]. +- This file does not support the [_augments_ key][Augments#augments]. ### def.json The file `def.json` is found based on the location of the policy entry (the first policy file read by the agent): -* with no arguments, it's in `$(sys.inputdir)/def.json` because +- with no arguments, it's in `$(sys.inputdir)/def.json` because `$(sys.inputdir)/promises.cf` is used -* with `-f /dirname/myfile.cf`, it's in `/dirname/def.json` -* with `-f ./myfile.cf`, it's in `./def.json` +- with `-f /dirname/myfile.cf`, it's in `/dirname/def.json` +- with `-f ./myfile.cf`, it's in `./def.json` **Notes:** -* `sys` variables are expanded in `def.json` and all subsequently loaded augments as specified by the `augments` key. -* `def_preferred.json` will be used instead of `def.json` if it is present. This preferential loading can be disabled by providing the `--ignore-preferred-augments` option to the agent. +- `sys` variables are expanded in `def.json` and all subsequently loaded augments as specified by the `augments` key. +- `def_preferred.json` will be used instead of `def.json` if it is present. This preferential loading can be disabled by providing the `--ignore-preferred-augments` option to the agent. ## Augments keys @@ -92,12 +92,12 @@ Filenames entered here will appear in the `def.augments_inputs` variable. **Notes:** -* Files are loaded relative to `sys.policy_entry_dirname`. +- Files are loaded relative to `sys.policy_entry_dirname`. -* The *inputs* key has precedence over the *vars* key. +- The _inputs_ key has precedence over the _vars_ key. -* If both the _inputs_ key and `vars.augments_inputs` are populated concurrently, - the variable `def.augments_inputs` will hold the value set by the *inputs* +- If both the _inputs_ key and `vars.augments_inputs` are populated concurrently, + the variable `def.augments_inputs` will hold the value set by the _inputs_ key. The `def.augments_inputs` variable is part of the default inputs in the `Masterfiles Policy Framework`. @@ -124,7 +124,7 @@ The above Augments results in `$(sys.policy_entry_dirname)/goodbye.cf` being add This key is supported in both `host_specific.json`, `def.json`, `def_preferred.json`, and augments loaded by the [_augments_ key][Augments#augments]. -Variables defined here can target a _namespace_ and or _bundle_ scope explicitly. When defined from `host_specific.json`, variables default to the ```variables``` _bundle_ in the ```data``` _namespace_ (`$(data:variables.MyVariable)`). +Variables defined here can target a _namespace_ and or _bundle_ scope explicitly. When defined from `host_specific.json`, variables default to the `variables` _bundle_ in the `data` _namespace_ (`$(data:variables.MyVariable)`). For example: @@ -218,12 +218,12 @@ bundle agent my_bundle **Notes:** -* ```vars``` and ```variables``` keys are allowed concurrently in the same file. -* If ```vars``` and ```variables``` keys in the same augments file define the same variable, the definition provided by the **```variables``` key wins**. +- `vars` and `variables` keys are allowed concurrently in the same file. +- If `vars` and `variables` keys in the same augments file define the same variable, the definition provided by the **`variables` key wins**. **History:** -* Added in 3.18.0 +- Added in 3.18.0 ### vars @@ -283,12 +283,12 @@ Variables of other types than string can be defined too, like in this example **Notes:** -* ```vars``` and ```variables``` keys are allowed concurrently in the same file. -* If ```vars``` and ```variables``` keys in the same augments file define the same variable, the definition provided by the **```variables``` key wins**. +- `vars` and `variables` keys are allowed concurrently in the same file. +- If `vars` and `variables` keys in the same augments file define the same variable, the definition provided by the **`variables` key wins**. **History:** -* 3.18.0 gained ability to specify the _namespace_ and _bundle_ the variable should be defined in. +- 3.18.0 gained ability to specify the _namespace_ and _bundle_ the variable should be defined in. ### classes @@ -299,8 +299,8 @@ Any class defined via augments will be evaluated and installed as _array_ and _dict_ formats. For an array each element of the array is tested against currently defined -classes as an [anchored regular expression][anchored] unless the string ends with ```::``` indicating it should be interpreted as a -[*class expression*][Classes and decisions]. +classes as an [anchored regular expression][anchored] unless the string ends with `::` indicating it should be interpreted as a +[_class expression_][Classes and decisions]. **For example:** @@ -386,46 +386,46 @@ for use. Thus: results in -* `augments_class_from_rgex_my_always` being always defined. +- `augments_class_from_rgex_my_always` being always defined. -* `augments_class_from_regex_my_other_apache` will be defined if the classes +- `augments_class_from_regex_my_other_apache` will be defined if the classes `server3` or `server4` are defined, or if any class starting with `debian` is defined. -* `augments_class_from_regex_my_other_always` will be defined because +- `augments_class_from_regex_my_other_always` will be defined because `augments_class_from_regex_my_always` is listed first and always defined. -* `augments_class_from_regex_when_MISSING_not_defined` will be defined if the +- `augments_class_from_regex_when_MISSING_not_defined` will be defined if the class `MISSING` is not defined. -* `augments_class_from_single_class_as_regex` will be defined because the class +- `augments_class_from_single_class_as_regex` will be defined because the class `cfengine` is always defined. -* `augments_class_from_single_class_as_expression` will be defined because +- `augments_class_from_single_class_as_expression` will be defined because `cfengine` is defined when interpreted as a class expression. -* `augments_class_from_classexpression_and` will be defined because the class +- `augments_class_from_classexpression_and` will be defined because the class `cfengine` and the class `cfengine_3` are defined and the class expression `cfengine.cfengine_3::` evaluates to true. -* `augments_class_from_classexpression_not` will be defined because the class +- `augments_class_from_classexpression_not` will be defined because the class expression `!MISSING::` evaluates to false since the class `MISSING` is not defined. -* `augments_class_from_classexpression_or` will be defined because the class +- `augments_class_from_classexpression_or` will be defined because the class expression `cfengine|cfengine_3::` evaluates to true since at least one of `cfengine` or `cfengine_3` will always be defined by cfengine 3 agents. -* `augments_class_from_classexpression_complex` will be defined because the +- `augments_class_from_classexpression_complex` will be defined because the class expression `(cfengine|cfengine_3).!MISSING::` evaluates to true since at least one of `cfengine` or `cfengine_3` will always be defined by cfengine 3 agents and `MISSING` is not defined. -* `myclass_defined_by_augments_in_def_json_3_18_0_v0` will be defined because +- `myclass_defined_by_augments_in_def_json_3_18_0_v0` will be defined because the class expression `cfengine|linux::` will always be true since there is always a `cfengine` class defined. -* `myclass_defined_by_augments_in_def_json_3_18_0_v1` will be defined because the expression `cfengine.**` will match at least one defined class, `cfengine` +- `myclass_defined_by_augments_in_def_json_3_18_0_v1` will be defined because the expression `cfengine.**` will match at least one defined class, `cfengine` You can see the list of classes thus defined through `def.json` in the output of `cf-promises --show-classes` (see [Components][]). They @@ -443,14 +443,14 @@ myclass_defined_by_augments_in_def_json_3_18_0_v1 optional,tags,sourc **See also:** -* Functions that use regular expressions with classes: `classesmatching()`, +- Functions that use regular expressions with classes: `classesmatching()`, `classmatch()`, `countclassesmatching()` **History:** -* 3.18.0 - * Support for dict structure for classes and support for metadata (`comment`, `tags`) added. - * Classes are defined as _soft_ classes instead of _hard_ classes. +- 3.18.0 + - Support for dict structure for classes and support for metadata (`comment`, `tags`) added. + - Classes are defined as _soft_ classes instead of _hard_ classes. ### augments @@ -499,16 +499,16 @@ R: def.centos_6_var == Defined ONLY in centos_6.json ## History -* 3.18.0 - * Introduced `variables` key with support for metadata (`comment`, `tags`) and targeting the _namespace_ and _bundle_. - * Introduced ability for `vars` to target _namespace_ and _bundle_ `variables` key with support for metadata (`comment`, `tags`). - * Introduced metadata (`comment`, `tags`) support for `classes` key. - * Introduced `def_preferred.json` and `--ignore-preferred-augments` to disable it. - * Classes defined from augments are now _soft_ classes and not _hard_ classes. - * Introduced parsing of `$(sys.workdir)/data/host_specific.json` -* 3.12.2, 3.14.0 introduced class expression interpretation (`::` suffix) to classes key -* 3.12.0 introduced the `augments` key -* 3.7.3 back port `def.json` parsing in core agent and load `def.json` if present next to policy entry -* 3.8.2 removed core support for `inputs` key, load `def.json` if present next to policy entry -* 3.8.1 `def.json` parsing moved from policy to core agent for resolution of classes and variables to be able to affect control bodies -* 3.7.0 introduced augments concept into the Masterfiles Policy Framework +- 3.18.0 + - Introduced `variables` key with support for metadata (`comment`, `tags`) and targeting the _namespace_ and _bundle_. + - Introduced ability for `vars` to target _namespace_ and _bundle_ `variables` key with support for metadata (`comment`, `tags`). + - Introduced metadata (`comment`, `tags`) support for `classes` key. + - Introduced `def_preferred.json` and `--ignore-preferred-augments` to disable it. + - Classes defined from augments are now _soft_ classes and not _hard_ classes. + - Introduced parsing of `$(sys.workdir)/data/host_specific.json` +- 3.12.2, 3.14.0 introduced class expression interpretation (`::` suffix) to classes key +- 3.12.0 introduced the `augments` key +- 3.7.3 back port `def.json` parsing in core agent and load `def.json` if present next to policy entry +- 3.8.2 removed core support for `inputs` key, load `def.json` if present next to policy entry +- 3.8.1 `def.json` parsing moved from policy to core agent for resolution of classes and variables to be able to affect control bodies +- 3.7.0 introduced augments concept into the Masterfiles Policy Framework diff --git a/content/reference/language-concepts/bodies.markdown b/content/reference/language-concepts/bodies.markdown index 84f5438d2..168220114 100644 --- a/content/reference/language-concepts/bodies.markdown +++ b/content/reference/language-concepts/bodies.markdown @@ -47,7 +47,7 @@ body perms mog(mode,user,group) } ``` -Like [bundles][bundles], bodies have a *type*. The type of the body has to match the left-hand side of the promise attribute in which it is used. In this case, `files` promises have an attribute `perms` that can be associated with any body of type `perms`. +Like [bundles][bundles], bodies have a _type_. The type of the body has to match the left-hand side of the promise attribute in which it is used. In this case, `files` promises have an attribute `perms` that can be associated with any body of type `perms`. The attributes within the body are then type specific. Bodies of type `perms` consist of the file permissions, the file owner, and the file group, which the instance `system` sets to `644`, `root` and `root`, respectively. @@ -139,7 +139,7 @@ whatever `$(x)` is, **overwriting** the value from `system`. Then The `mode` attribute will be **overwritten** to `645` in `system_once` and then **overwritten** to `646` in `system_twice`. -If this gets complicated, just think *"latest wins"*. +If this gets complicated, just think _"latest wins"_. #### Implicit, Control Bodies diff --git a/content/reference/language-concepts/bundles.markdown b/content/reference/language-concepts/bundles.markdown index 854b31c12..98485a7e0 100644 --- a/content/reference/language-concepts/bundles.markdown +++ b/content/reference/language-concepts/bundles.markdown @@ -13,15 +13,15 @@ related to configuring a web server or a file system would be named **NOTE**: Bundles **are not functions**. They maintain state across actuations within the same agent run. -* Classic arrays are cleared at the beginning of a bundle actuation. -* Lists, strings, ints, reals, and data-containers are preserved but can be - re-defined if not guarded with ```if => isvariable()```. -* `bundle` scoped classes are cleared at the end of the bundles execution -* `namespace` scoped classes are not cleared automatically, though they can be +- Classic arrays are cleared at the beginning of a bundle actuation. +- Lists, strings, ints, reals, and data-containers are preserved but can be + re-defined if not guarded with `if => isvariable()`. +- `bundle` scoped classes are cleared at the end of the bundles execution +- `namespace` scoped classes are not cleared automatically, though they can be explicitly undefined. Most promise types are specific to a particular kind of interpretation that -requires a typed interpreter - the bundle *type*. Bundles belong to the agent +requires a typed interpreter - the bundle _type_. Bundles belong to the agent that is used to keep the promises in the bundle. So `cf-agent` has bundles declared as: @@ -78,10 +78,10 @@ recipient. These are the specific evaluation differences between common and agent bundles: -* common bundles are automatically evaluated even if they are not in the bundlesequence, as long as they have no parameters -* auto-evaluated common bundles (not in the bundlesequence explicitly) don't evaluate their `reports` promises, so their reports won't be printed. -* when common bundles define a class, it's global ([`scope`][classes#scope] is `namespace`) by default; the classes in agent bundles are local ([`scope`][classes#scope] is `bundle`) by default. -* common bundles can only contain [`meta`][meta], `default`, `vars`, [`classes`][classes], and `reports` promises +- common bundles are automatically evaluated even if they are not in the bundlesequence, as long as they have no parameters +- auto-evaluated common bundles (not in the bundlesequence explicitly) don't evaluate their `reports` promises, so their reports won't be printed. +- when common bundles define a class, it's global ([`scope`][classes#scope] is `namespace`) by default; the classes in agent bundles are local ([`scope`][classes#scope] is `bundle`) by default. +- common bundles can only contain [`meta`][meta], `default`, `vars`, [`classes`][classes], and `reports` promises ### Bundle Parameters @@ -127,7 +127,7 @@ bundle agent subtest_c(info) ``` You can pass `slist` and `data` variables to other bundles with -the `@(var)` notation. You do NOT need to qualify the variable name +the `@(var)` notation. You do NOT need to qualify the variable name with the current bundle name. ### Scope @@ -142,7 +142,7 @@ qualify the name, using the name of the bundle in which it is defined: The value of the variable depends on evaluation order, which is not controllable by the user. Thus you should not assume that you can evaluate a bundle twice with different variables and get variables -from it that correspond to the second evaluation. In other words, if you have: +from it that correspond to the second evaluation. In other words, if you have: ```cf3 bundle agent mybundle(x) @@ -161,8 +161,8 @@ scoped. [Classes][classes and decisions] defined by `classes` type promises in Note that namespaced bundles work exactly the same way as non-namespaced bundles (which are actually in the `default` -namespace). You just say `namespace:bundle_name` instead of -`bundle_name`. See [Namespaces] for more details. +namespace). You just say `namespace:bundle_name` instead of +`bundle_name`. See [Namespaces] for more details. ### Main bundles and bundlesequence @@ -171,6 +171,7 @@ The default `bundlesequence` contains `main` for convenience, so this example wo {{< CFEngine_include_example(main.cf) >}} #### Custom bundle sequences + You can specify a custom `bundlesequence` from the command line using `--bundlesequence`, or in policy: {{< CFEngine_include_example(bundlesequence.cf) >}} diff --git a/content/reference/language-concepts/classes.markdown b/content/reference/language-concepts/classes.markdown index adb469755..f38e17bc5 100644 --- a/content/reference/language-concepts/classes.markdown +++ b/content/reference/language-concepts/classes.markdown @@ -57,8 +57,8 @@ the `/var/cfengine/state/env_data` file is secure. The `classesmatching()` function searches using a regular expression for classes matching a given name and or tag. -**See also:** The ```--show-vars``` option for `cf-promises` and the -```--show-evaluated-vars``` option for `cf-agent`. +**See also:** The `--show-vars` option for `cf-promises` and the +`--show-evaluated-vars` option for `cf-agent`. ## Tags @@ -67,29 +67,29 @@ created them) and purpose (why were they created). While you can provide your own tags for soft classes in policy with the [`meta`][Promise types#meta] attribute, there are some tags applied to hard classes and -other special cases. This list may change in future versions of +other special cases. This list may change in future versions of CFEngine. -* `source=agent`: this hard class or variable was created by the agent in the C code. This tag is useful when you need to find classes or variables that don't match the other sources below. e.g. `linux`. -* `source=environment`: this hard class or variable was created by the agent in the C code. It reflects something about the environment like a command-line option, e.g. `-d` sets `debug_mode`, `-v` sets `verbose_mode`, and `-I` sets `inform_mode`. Another useful option, `-n`, sets `opt_dry_run`. -* `source=bootstrap`: this hard class or variable was created by the agent in the C code based on bootstrap parameters. e.g. `policy_server` is set based on the IP address or host name you provided when you ran `cf-agent -B host-or-ip`. -* `source=module`: this class or variable was created through the module protocol. -* `source=persistent`: this persistent class was loaded from storage. -* `source=body`: this variable was created by a body with side effects. -* `source=function`: this class or variable was created by a function as a side effect, e.g. see the classes that `selectservers()` sets or the variables that `regextract()` sets. These classes or variables will also have a `function=FUNCTIONNAME` tag. -* `source=promise`: this soft class was created from policy. -* `inventory`: related to the system inventory, e.g. the network interfaces - * `attribute_name=none`: has no visual attribute name (ignored by Mission Portal) - * `attribute_name=X`: has visual attribute name `X` (used by Mission Portal) -* `monitoring`: related to the monitoring (`cf-monitord` usually). -* `time_based`: based on the system date, e.g. `Afternoon` -* `derived-from=varname`: for a class, this tells you it was derived from a variable name, e.g. if the special variable `sys.fqhost` is `xyz`, the resulting class `xyz` will have the tag `derived-from=sys.fqhost`. -* `cfe_internal`: internal utility classes and variables +- `source=agent`: this hard class or variable was created by the agent in the C code. This tag is useful when you need to find classes or variables that don't match the other sources below. e.g. `linux`. +- `source=environment`: this hard class or variable was created by the agent in the C code. It reflects something about the environment like a command-line option, e.g. `-d` sets `debug_mode`, `-v` sets `verbose_mode`, and `-I` sets `inform_mode`. Another useful option, `-n`, sets `opt_dry_run`. +- `source=bootstrap`: this hard class or variable was created by the agent in the C code based on bootstrap parameters. e.g. `policy_server` is set based on the IP address or host name you provided when you ran `cf-agent -B host-or-ip`. +- `source=module`: this class or variable was created through the module protocol. +- `source=persistent`: this persistent class was loaded from storage. +- `source=body`: this variable was created by a body with side effects. +- `source=function`: this class or variable was created by a function as a side effect, e.g. see the classes that `selectservers()` sets or the variables that `regextract()` sets. These classes or variables will also have a `function=FUNCTIONNAME` tag. +- `source=promise`: this soft class was created from policy. +- `inventory`: related to the system inventory, e.g. the network interfaces + - `attribute_name=none`: has no visual attribute name (ignored by Mission Portal) + - `attribute_name=X`: has visual attribute name `X` (used by Mission Portal) +- `monitoring`: related to the monitoring (`cf-monitord` usually). +- `time_based`: based on the system date, e.g. `Afternoon` +- `derived-from=varname`: for a class, this tells you it was derived from a variable name, e.g. if the special variable `sys.fqhost` is `xyz`, the resulting class `xyz` will have the tag `derived-from=sys.fqhost`. +- `cfe_internal`: internal utility classes and variables Enterprise only: -* `source=ldap`: this soft class or variable was created from an LDAP lookup. -* `source=observation`: this class or variable came from a `measurements` system observation and will also have the `monitoring` tag. +- `source=ldap`: this soft class or variable was created from an LDAP lookup. +- `source=observation`: this class or variable came from a `measurements` system observation and will also have the `monitoring` tag. ## Hard classes @@ -112,86 +112,86 @@ of a week. **Notes:** -* Hard classes can **not** be undefined. If you try to undefine or cancel a hard +- Hard classes can **not** be undefined. If you try to undefine or cancel a hard class an error will be emitted, for example `error: You cannot cancel a - reserved hard class 'cfengine' in post-condition classes`. - -* CFEngine-specific classes - * `any`: this class is always set - * `cfengine`: This class is always defined. - * `cfengine_`: This class is always defined where `` represents the major version of CFEngine running. For example, `cfengine_3` is defined on all versions of CFEngine 3.x. - * `cfengine__`: This class is always defined where `` represents the major version of CFEngine running and `` represents the minor version. For example, `cfengine_3_24` is defined on all versions of CFEngine 3.24.x. - * `cfengine___`: This class is always defined where `` represents the major version of CFEngine running, `` represents the minor version, and `` represents the patch version. For example, `cfengine_3_24_0` is defined only on CFEngine 3.24.0. - * `am_policy_hub`, `policy_server`: set when the file - `$(workdir)/state/am_policy_hub` exists. When a host is [bootstrapped][cf-agent], if - the agent detects that it is bootstrapping to itself the file is created. - * `bootstrap_mode`: set when bootstrapping a host - * `inform_mode`, `verbose_mode`, `debug_mode`: log verbosity levels in order of noisiness - * `opt_dry_run`: set when the `--dry-run` option is given - * `failsafe_fallback`: set when the base policy is invalid and the built-in `failsafe.cf` (see `bootstrap.c`) is invoked - * (`community`, `community_edition`) and (`enterprise`, `enterprise_edition`): the two different CFEngine products, Community and Enterprise, can be distinguished by these mutually exclusive sets of hard classes - * Component Specific Classes (each component has a class that is always considered defined by that component): - * `cf-agent` :: ```agent``` - * `cf-serverd` :: ```server``` - * `cf-monitord` :: ```monitor``` - * `cf-execd` :: ```executor``` - * `cf-runagent` :: ```runagent``` - * `cf-key` :: ```keygenerator``` - * `cf-hub` :: ```hub``` - * `cf-promises` :: ```common``` -* Operating System Classes (note that the presence of these classes doesn't imply platform support) - * Operating System Architecture - `arista`, `big_ip`, `debian`, `eos`, `fedora`, `Mandrake`, `Mandriva`, `oracle`, `redhat`, `slackware`, `smartmachine`, `smartos`, `solarisx86`, `sun4`, `SuSE`, `ubuntu`, `ultrix`, the always-favorite `unknown_ostype`, etc. - * VM or hypervisor specific: `VMware`, `virt_guest_vz`, `virt_host_vz`, `virt_host_vz_vzps`, `xen`, `xen_dom0`, `xen_domu_hv`, `xen_domu_pv`, `oraclevmserver`, etc. - * On Solaris-10 systems, the zone name (in the form `zone_global, zone_foo, zone_baz`). - * Windows-specific: `DomainController`, `Win2000`, `WinServer`, `WinServer2003`, `WinServer2008`, `WinVista`, `WinWorkstation`, `WinXP` - * `have_aptitude`, `powershell`, `systemd`: based on the detected capabilities of the platform or the compiled-in options - * **See also:** `sys.arch`, `sys.class`, `sys.flavor`, `sys.os`, `sys.ostype`. -* Network Classes - * Unqualified Name of Host. CFEngine truncates it at the first dot. - Note: `www.sales.company.com` and `www.research.company.com` have the - same unqualified name - `www` - * The IPv4 address octets of any active interface (in the form - `ipv4_192_0_0_1`, `ipv4_192_0_0`, `ipv4_192_0`, `ipv4_192`) - * The IPv6 addresses of all active interfaces (with dots replaced by - underscores, e.g. `ipv6_fe80__a410_6072_21eb_d3fa`) added in 3.7.8, 3.10.3, 3.12.0 - * User-defined Group of Hosts - * `mac_unknown`: set when the MAC address can't be found - * **See also:** `sys.domain`, `sys.hardware_addresses`, `sys.sys.host`, `sys.interface`, `sys.interfaces`, `sys.interface_flags`, `sys.ipv4`, `sys.ip_addresses`, `sys.fqhost`, `sys.uqhost`. -* Time Classes - * note ALL of these have a local and a GMT version. The GMT classes are consistent the world over, in case you need global change coordination. - * Day of the Week - `Monday, Tuesday, Wednesday,...GMT_Monday, GMT_Tuesday, GMT_Wednesday,...` - * Hour of the Day in Current Time Zone - `Hr00, Hr01,... Hr23` and `Hr0, Hr1,... Hr23` - * Hour of the Day in GMT - `GMT_Hr00, GMT_Hr01, ...GMT_Hr23` and `GMT_Hr0, GMT_Hr1, ...GMT_Hr23`. - * Minutes of the Hour - `Min00, Min17,... Min45,...` and `GMT_Min00, GMT_Min17,... GMT_Min45,...` - * Five Minute Interval of the Hour - `Min00_05, Min05_10,... Min55_00` and `GMT_Min00_05, GMT_Min05_10,... GMT_Min55_00`. Note the second number indicates *up to* what minute the interval extends and does not include that minute. - * Quarter of the Hour - `Q1, Q2, Q3, Q4` and `GMT_Q1, GMT_Q2, GMT_Q3, GMT_Q4` - * An expression of the current quarter hour - `Hr12_Q3` and `GMT_Hr12_Q3` - * Day of the Month - `Day1, Day2,... Day31` and `GMT_Day1, GMT_Day2,... GMT_Day31` - * Month - `January, February,... December` and `GMT_January, GMT_February,... GMT_December` - * Year - `Yr1997, Yr2004` and `GMT_Yr1997, GMT_Yr2004` - * Period of the Day - `Night, Morning, Afternoon, Evening` and `GMT_Night, GMT_Morning, GMT_Afternoon, GMT_Evening` (six hour blocks starting at 00:00 hours). - * Lifecycle Index - `Lcycle_0, Lcycle_1, Lcycle_2` and `GMT_Lcycle_0, GMT_Lcycle_1, GMT_Lcycle_2` (the year number modulo 3, used in long term resource memory). - * **See also:** `sys.cdate`, `sys.date`. - -- The unqualified name of a particular host (e.g., `www`). If - your system returns a fully qualified domain name for your host - (e.g., `www.iu.hio.no`), CFEngine will also define a hard class for - the fully qualified name, as well as the partially-qualified - component names `iu.hio.no`, `hio.no`, and `no`. - * **See also:** `sys.fqhost`, `sys.uqhost`. -- An arbitrary user-defined string (as specified in the `-D` - command line option, or defined in a [`classes` promise][classes] promise or - [`classes` body][Promise types#classes], - `restart_class` in a `processes` promise, etc). -- The IP address octets of any active interface (in the form `ipv4_192_0_0_1`, - `ipv4_192_0_0`, `ipv4_192_0`, `ipv4_192`), provided they are not excluded by - a regular expression in the file `WORKDIR/ignore_interfaces.rx` or `WORKDIR/inputs/ignore_interfaces.rx`. - - Note: Support and preference for `WORKDIR/ignore_interfaces.rx` was added - and is present in version `3.23.0` and later and in version `3.21.4` and later. -- The names of the active interfaces (in the form - `net_iface_xl0`, `net_iface_vr0`). -- System status and entropy information reported by - `cf-monitord`. +reserved hard class 'cfengine' in post-condition classes`. + +- CFEngine-specific classes + - `any`: this class is always set + - `cfengine`: This class is always defined. + - `cfengine_`: This class is always defined where `` represents the major version of CFEngine running. For example, `cfengine_3` is defined on all versions of CFEngine 3.x. + - `cfengine__`: This class is always defined where `` represents the major version of CFEngine running and `` represents the minor version. For example, `cfengine_3_24` is defined on all versions of CFEngine 3.24.x. + - `cfengine___`: This class is always defined where `` represents the major version of CFEngine running, `` represents the minor version, and `` represents the patch version. For example, `cfengine_3_24_0` is defined only on CFEngine 3.24.0. + - `am_policy_hub`, `policy_server`: set when the file + `$(workdir)/state/am_policy_hub` exists. When a host is [bootstrapped][cf-agent], if + the agent detects that it is bootstrapping to itself the file is created. + - `bootstrap_mode`: set when bootstrapping a host + - `inform_mode`, `verbose_mode`, `debug_mode`: log verbosity levels in order of noisiness + - `opt_dry_run`: set when the `--dry-run` option is given + - `failsafe_fallback`: set when the base policy is invalid and the built-in `failsafe.cf` (see `bootstrap.c`) is invoked + - (`community`, `community_edition`) and (`enterprise`, `enterprise_edition`): the two different CFEngine products, Community and Enterprise, can be distinguished by these mutually exclusive sets of hard classes + - Component Specific Classes (each component has a class that is always considered defined by that component): + - `cf-agent` :: `agent` + - `cf-serverd` :: `server` + - `cf-monitord` :: `monitor` + - `cf-execd` :: `executor` + - `cf-runagent` :: `runagent` + - `cf-key` :: `keygenerator` + - `cf-hub` :: `hub` + - `cf-promises` :: `common` +- Operating System Classes (note that the presence of these classes doesn't imply platform support) + - Operating System Architecture - `arista`, `big_ip`, `debian`, `eos`, `fedora`, `Mandrake`, `Mandriva`, `oracle`, `redhat`, `slackware`, `smartmachine`, `smartos`, `solarisx86`, `sun4`, `SuSE`, `ubuntu`, `ultrix`, the always-favorite `unknown_ostype`, etc. + - VM or hypervisor specific: `VMware`, `virt_guest_vz`, `virt_host_vz`, `virt_host_vz_vzps`, `xen`, `xen_dom0`, `xen_domu_hv`, `xen_domu_pv`, `oraclevmserver`, etc. + - On Solaris-10 systems, the zone name (in the form `zone_global, zone_foo, zone_baz`). + - Windows-specific: `DomainController`, `Win2000`, `WinServer`, `WinServer2003`, `WinServer2008`, `WinVista`, `WinWorkstation`, `WinXP` + - `have_aptitude`, `powershell`, `systemd`: based on the detected capabilities of the platform or the compiled-in options + - **See also:** `sys.arch`, `sys.class`, `sys.flavor`, `sys.os`, `sys.ostype`. +- Network Classes + - Unqualified Name of Host. CFEngine truncates it at the first dot. + Note: `www.sales.company.com` and `www.research.company.com` have the + same unqualified name - `www` + - The IPv4 address octets of any active interface (in the form + `ipv4_192_0_0_1`, `ipv4_192_0_0`, `ipv4_192_0`, `ipv4_192`) + - The IPv6 addresses of all active interfaces (with dots replaced by + underscores, e.g. `ipv6_fe80__a410_6072_21eb_d3fa`) added in 3.7.8, 3.10.3, 3.12.0 + - User-defined Group of Hosts + - `mac_unknown`: set when the MAC address can't be found + - **See also:** `sys.domain`, `sys.hardware_addresses`, `sys.sys.host`, `sys.interface`, `sys.interfaces`, `sys.interface_flags`, `sys.ipv4`, `sys.ip_addresses`, `sys.fqhost`, `sys.uqhost`. +- Time Classes + - note ALL of these have a local and a GMT version. The GMT classes are consistent the world over, in case you need global change coordination. + - Day of the Week - `Monday, Tuesday, Wednesday,...GMT_Monday, GMT_Tuesday, GMT_Wednesday,...` + - Hour of the Day in Current Time Zone - `Hr00, Hr01,... Hr23` and `Hr0, Hr1,... Hr23` + - Hour of the Day in GMT - `GMT_Hr00, GMT_Hr01, ...GMT_Hr23` and `GMT_Hr0, GMT_Hr1, ...GMT_Hr23`. + - Minutes of the Hour - `Min00, Min17,... Min45,...` and `GMT_Min00, GMT_Min17,... GMT_Min45,...` + - Five Minute Interval of the Hour - `Min00_05, Min05_10,... Min55_00` and `GMT_Min00_05, GMT_Min05_10,... GMT_Min55_00`. Note the second number indicates _up to_ what minute the interval extends and does not include that minute. + - Quarter of the Hour - `Q1, Q2, Q3, Q4` and `GMT_Q1, GMT_Q2, GMT_Q3, GMT_Q4` + - An expression of the current quarter hour - `Hr12_Q3` and `GMT_Hr12_Q3` + - Day of the Month - `Day1, Day2,... Day31` and `GMT_Day1, GMT_Day2,... GMT_Day31` + - Month - `January, February,... December` and `GMT_January, GMT_February,... GMT_December` + - Year - `Yr1997, Yr2004` and `GMT_Yr1997, GMT_Yr2004` + - Period of the Day - `Night, Morning, Afternoon, Evening` and `GMT_Night, GMT_Morning, GMT_Afternoon, GMT_Evening` (six hour blocks starting at 00:00 hours). + - Lifecycle Index - `Lcycle_0, Lcycle_1, Lcycle_2` and `GMT_Lcycle_0, GMT_Lcycle_1, GMT_Lcycle_2` (the year number modulo 3, used in long term resource memory). + - **See also:** `sys.cdate`, `sys.date`. + +* The unqualified name of a particular host (e.g., `www`). If + your system returns a fully qualified domain name for your host + (e.g., `www.iu.hio.no`), CFEngine will also define a hard class for + the fully qualified name, as well as the partially-qualified + component names `iu.hio.no`, `hio.no`, and `no`. + - **See also:** `sys.fqhost`, `sys.uqhost`. +* An arbitrary user-defined string (as specified in the `-D` + command line option, or defined in a [`classes` promise][classes] promise or + [`classes` body][Promise types#classes], + `restart_class` in a `processes` promise, etc). +* The IP address octets of any active interface (in the form `ipv4_192_0_0_1`, + `ipv4_192_0_0`, `ipv4_192_0`, `ipv4_192`), provided they are not excluded by + a regular expression in the file `WORKDIR/ignore_interfaces.rx` or `WORKDIR/inputs/ignore_interfaces.rx`. +* Note: Support and preference for `WORKDIR/ignore_interfaces.rx` was added + and is present in version `3.23.0` and later and in version `3.21.4` and later. +* The names of the active interfaces (in the form + `net_iface_xl0`, `net_iface_vr0`). +* System status and entropy information reported by + `cf-monitord`. ## Soft classes @@ -243,7 +243,7 @@ $ cf-promises -f ./promises.cf -D dev 2014-05-22T13:46:05+0000 error: There are syntax errors in policy files ``` -*Note*: Classes, once defined, will stay defined either for as long as the +_Note_: Classes, once defined, will stay defined either for as long as the bundle is evaluated (for classes with a `bundle` scope) or until the agent exits (for classes with a `namespace` scope). See `cancel_kept`, `cancel_repaired`, and `cancel_notkept` in classes body. @@ -268,19 +268,19 @@ reports: } ``` -* The `always` and `always2` soft classes are always defined. +- The `always` and `always2` soft classes are always defined. -* The `solinux` soft class is defined as a combination of the `linux` or the +- The `solinux` soft class is defined as a combination of the `linux` or the `solaris` hard classes. This class will be set if the operating system family is either of these values. -* The `alt_class` soft class is defined as a combination of `linux`, +- The `alt_class` soft class is defined as a combination of `linux`, `solaris`, or the presence of a file named `/etc/fstab`. If one of the two hard classes evaluate to true, or if there is a file named `/etc/fstab`, the `alt_class` class will also be set. -* The `oth_class` soft class is defined as the combination of two `fileexists` - functions - `/etc/shadow` and `/etc/passwd`. If both of these files are +- The `oth_class` soft class is defined as the combination of two `fileexists` + functions - `/etc/shadow` and `/etc/passwd`. If both of these files are present the `oth_class` class will also be set. ### Negative knowledge @@ -479,25 +479,25 @@ For example `a . b` is equivalent to `a.b` and perhaps more readable. Classes may be combined with the operators listed here in order from highest to lowest precedence: -* '()':: - ~ The parenthesis group operator. +- '()':: + ~ The parenthesis group operator. -* '!':: - ~ The NOT operator. +- '!':: + ~ The NOT operator. -* '.':: - ~ The AND operator. +- '.':: + ~ The AND operator. -* '&':: - ~ The AND operator (alternative). +- '&':: + ~ The AND operator (alternative). -* '|':: - ~ The OR operator. +- '|':: + ~ The OR operator. -* '||':: - ~ The OR operator (alternative). +- '||':: + ~ The OR operator (alternative). -These operators can be combined to form complex expressions. For example, the +These operators can be combined to form complex expressions. For example, the following expression would be only true on Mondays or Wednesdays from 2:00pm to 2:59pm on Windows XP systems: @@ -604,8 +604,8 @@ These classes are `namespace` scoped by default. The local to the bundle. It is recommended to use bundle scoped classes whenever possible. This example -will define ```signal_class``` prefixed classes with a suffix matching the -promise outcome (```_kept```, ```_repaired```, ```_notkept```). +will define `signal_class` prefixed classes with a suffix matching the +promise outcome (`_kept`, `_repaired`, `_notkept`). ```cf3 "promiser..." diff --git a/content/reference/language-concepts/loops.markdown b/content/reference/language-concepts/loops.markdown index c7cf115de..e244f4c2d 100644 --- a/content/reference/language-concepts/loops.markdown +++ b/content/reference/language-concepts/loops.markdown @@ -131,4 +131,4 @@ reports: This example uses two lists, `stats` and `monvars`. We can now iterate over both lists in the same promise. The reports that we thus generate will report on `value_rootprocs`, `av_rootprocs`, and `dev_rootprocs`, followed next by `value_otherprocs`, `av_otherprocs`, etc, ending finally with `dev_loadavg`. -The order of iteration is an implementation detail and should not be expected to be consistent. Use the `sort()` function if you need to sort a list in a predictable way. +The order of iteration is an implementation detail and should not be expected to be consistent. Use the `sort()` function if you need to sort a list in a predictable way. diff --git a/content/reference/language-concepts/modules/_index.markdown b/content/reference/language-concepts/modules/_index.markdown index c864b3949..762d40c2c 100644 --- a/content/reference/language-concepts/modules/_index.markdown +++ b/content/reference/language-concepts/modules/_index.markdown @@ -15,25 +15,25 @@ cfbs (CFEngine Build System) Modules provide a way to share and consume CFEngine ## Promise modules -Promise modules allow for the implementation of [*custom* promise types][promise-type-custom], extending the CFEngine Language. They communicate with `cf-agent` using the [*Promise Module Protocol*][promise-type-custom-protocol]. +Promise modules allow for the implementation of [_custom_ promise types][promise-type-custom], extending the CFEngine Language. They communicate with `cf-agent` using the [_Promise Module Protocol_][promise-type-custom-protocol]. **History:** -* Introduced 3.17.0 +- Introduced 3.17.0 ## Package modules -[Package modules][Package modules] implement the logic behind *packages* type promises, superseding the *package\_method* based implementation. They interact with package managers like `yum`, `apt`, `msiexec`, and `pip` to determine which packages are currently installed or have updates available as well as installing, upgrading or un-installing packages. +[Package modules][Package modules] implement the logic behind _packages_ type promises, superseding the _package_method_ based implementation. They interact with package managers like `yum`, `apt`, `msiexec`, and `pip` to determine which packages are currently installed or have updates available as well as installing, upgrading or un-installing packages. Package modules communicate with `cf-agent` via the [Package Module Protocol][package-modules-the-api]. **History:** -* Introduced 3.7.0 +- Introduced 3.7.0 ## Variables and classes modules -Variables and classes modules are the original way to extend CFEngine. The Variable and Class Module Protocol allows for *variables* and *classes* to be defined. The protocol can be interpreted by functions like [`usemodule()`][usemodule] and [`read_module_protocol()`][read_module_protocol] as well as output from [*commands* type promises][commands] with the [`module => "true"`][commands#module] attribute. +Variables and classes modules are the original way to extend CFEngine. The Variable and Class Module Protocol allows for _variables_ and _classes_ to be defined. The protocol can be interpreted by functions like [`usemodule()`][usemodule] and [`read_module_protocol()`][read_module_protocol] as well as output from [_commands_ type promises][commands] with the [`module => "true"`][commands#module] attribute. The choice of interpretation can depend on many factors but a primary differentiate between functions and classes relate to CFEngine's evaluation details. Functions are evaluated early during policy execution unless they are explicitly guarded to delay execution. Commands promises are not executed until the bundle is actuated for it's three pass evaluation. @@ -41,25 +41,25 @@ Variables and classes modules are intended for use as system probes rather than ### Specification -The protocol is *line based*. Lines that begin with `^` apply to all following lines. +The protocol is _line based_. Lines that begin with `^` apply to all following lines. -* **`^context=BundleName`:** Sets the bundle scope in which *variables* will be defined -* **`^meta=Tag1,Tag2`:** Sets a comma separated list of tags that are applied to defined *variables* and *classes* -* **`^persistence=X`:** Sets the number of minutes for which *classes* should persist -* **`+ClassName`:** Defines a namespace scoped class -* **`-ClassName`:** Undefines a class -* **`=VariableName=`:** Defines a string variable -* **`VariableName[KEY]=`:** Defines an associative array key value -* **`@VariableName=`:** Defines a list of strings -* **`%VariableName=`:** Must be valid JSON and defines a data container +- **`^context=BundleName`:** Sets the bundle scope in which _variables_ will be defined +- **`^meta=Tag1,Tag2`:** Sets a comma separated list of tags that are applied to defined _variables_ and _classes_ +- **`^persistence=X`:** Sets the number of minutes for which _classes_ should persist +- **`+ClassName`:** Defines a namespace scoped class +- **`-ClassName`:** Undefines a class +- **`=VariableName=`:** Defines a string variable +- **`VariableName[KEY]=`:** Defines an associative array key value +- **`@VariableName=`:** Defines a list of strings +- **`%VariableName=`:** Must be valid JSON and defines a data container **Notes:** -* It is not possible to define variables or classes in a namespace other than the default (`default`). -* If no context is provided, the context is the canonified leaf name of the module. For example, if the module is `/tmp/path/my-module.sh` the default context would be `my_module_sh` in the `default` namespace (`default:my_module_sh`). -* All *variables* and *classes* will be tagged with `source=module` in addition to any specified tags. -* All lines of output that do not match the module protocol are treated as *errors*. -* Variable names defined by the module protocol are limited to alphanumeric characters and `_`, `.`, `-`, `[`, `]`, `@`, and `/`. +- It is not possible to define variables or classes in a namespace other than the default (`default`). +- If no context is provided, the context is the canonified leaf name of the module. For example, if the module is `/tmp/path/my-module.sh` the default context would be `my_module_sh` in the `default` namespace (`default:my_module_sh`). +- All _variables_ and _classes_ will be tagged with `source=module` in addition to any specified tags. +- All lines of output that do not match the module protocol are treated as _errors_. +- Variable names defined by the module protocol are limited to alphanumeric characters and `_`, `.`, `-`, `[`, `]`, `@`, and `/`. **Examples:** @@ -78,8 +78,8 @@ A Variables and Classes module written in shell: **History:** -- Introduced in 3.0.0 -- `^context`, `^meta` Added in 3.6.0 -- `^persistence` Added in 3.8.0 -- `@` allowed in variables (intended for keys in classic array) 3.15.0, 3.12.3, 3.10.7 (2019) -- `/` allowed in variables (intended for keys in classic array) 3.14.0, 3.12.2, 3.10.6 (2019) +- Introduced in 3.0.0 +- `^context`, `^meta` Added in 3.6.0 +- `^persistence` Added in 3.8.0 +- `@` allowed in variables (intended for keys in classic array) 3.15.0, 3.12.3, 3.10.7 (2019) +- `/` allowed in variables (intended for keys in classic array) 3.14.0, 3.12.2, 3.10.6 (2019) diff --git a/content/reference/language-concepts/modules/package-module-api.markdown b/content/reference/language-concepts/modules/package-module-api.markdown index 22c65e7f1..7966619f3 100644 --- a/content/reference/language-concepts/modules/package-module-api.markdown +++ b/content/reference/language-concepts/modules/package-module-api.markdown @@ -15,15 +15,15 @@ comprehensive reference on the body types and attributes used here. CFEngine never calls any package manager commands, it only ever calls the package module. The information that CFEngine deals in is: -* Which packages are currently installed: - * Name - * Version - * Architecture +- Which packages are currently installed: + - Name + - Version + - Architecture -* Which of the installed packages have updates available: - * Name - * Version - * Architecture +- Which of the installed packages have updates available: + - Name + - Version + - Architecture These two lists are everything that CFEngine needs to know to decide whether its package promises are fulfilled or not. In addition to this it will carry out @@ -82,7 +82,7 @@ This attribute has no inherent meaning to CFEngine. It is meant as a mechanism to communicate special attributes to the package module that are not covered by the main API. For example, for certain package modules it may be used to pass a repository URL, or pass options to the command line of the underlying -package tool. The behavior on an `options` attribute is entirely +package tool. The behavior on an `options` attribute is entirely dependent on the module, and should not be assumed to be portable between modules. @@ -141,7 +141,7 @@ Next, for file based package name it should return `Version` and `Architecture` if it is able to determine these, but it is allowed to omit them if the module doesn't know (if the resource is remote, for instance). -For repository based package names the module should *not* return `Version` and +For repository based package names the module should _not_ return `Version` and `Architecture`, since they are often ambiguous in repository situations, and any discrepancies will be handled at the install stage instead. @@ -263,7 +263,7 @@ It is not an error to include updates to packages that are not installed, but this information will not be used, and it is therefore recommended to omit it for performance purposes. -Unlike `list-updates`, this command is *not* expected to use the network to +Unlike `list-updates`, this command is _not_ expected to use the network to fetch information from external sources, but should fetch all the information from local storage. This command exists precisely to limit such expensive operations. @@ -288,7 +288,7 @@ $ ### repo-install This command is used by CFEngine to ask the package module to install packages -from the package repository. Note that CFEngine itself has no notion of *which* +from the package repository. Note that CFEngine itself has no notion of _which_ package repository it should come from. This is up to the package module, and may either be a platform configured default, such as is the case for for example yum, or a specific repository which is passed in via the `options` @@ -414,12 +414,12 @@ For performance reasons, CFEngine will cache the list of packages returned from `list-packages` and the list of updates from either of `list-updates` or `list-updates-local`. The exact circumstances where each is called is: -* `list-packages`: When either the system is changed, or +- `list-packages`: When either the system is changed, or `query_installed_ifelapsed` in the policy has expired. -* `list-updates`: Only when `query_updates_ifelapsed` in the policy has expired. +- `list-updates`: Only when `query_updates_ifelapsed` in the policy has expired. -* `list-updates-local`: Only when the system is changed. +- `list-updates-local`: Only when the system is changed. Whenever one is called its result is cached by CFEngine and will be used internally. It is a good idea to set the two policy attributes, diff --git a/content/reference/language-concepts/namespaces.markdown b/content/reference/language-concepts/namespaces.markdown index bdbe535c0..c67b92721 100644 --- a/content/reference/language-concepts/namespaces.markdown +++ b/content/reference/language-concepts/namespaces.markdown @@ -30,7 +30,7 @@ declared or until the end of the file. ## Methods|usebundle Methods promises assume you are referring to a bundle in the same namespace as -the promiser. To refer to a bundle in another namespace you *must* specify the +the promiser. To refer to a bundle in another namespace you _must_ specify the namespace by prefixing the bundle name with the namespace followed by a colon (`:`). @@ -52,7 +52,7 @@ as the promiser but can also be referenced fully qualified with the namespace. {{< CFEngine_include_example(namespace_variable_references.cf) >}} [Special variables][Special variables] are always accessible without a namespace - prefix. For example, `this`, `mon`, `sys`, and `const` fall in this category. +prefix. For example, `this`, `mon`, `sys`, and `const` fall in this category. {{< CFEngine_include_example(namespace_special_var_exception.cf) >}} diff --git a/content/reference/language-concepts/policy-evaluation.markdown b/content/reference/language-concepts/policy-evaluation.markdown index 179c1226f..78997af6b 100644 --- a/content/reference/language-concepts/policy-evaluation.markdown +++ b/content/reference/language-concepts/policy-evaluation.markdown @@ -13,7 +13,7 @@ editing in files. CFEngine solves this in a two-part strategy: CFEngine maintains a default order of promise-types, referred to as `Normal order`. This is based on a simple logic of what needs to come first, e.g. it makes no sense to create something and then delete it, but it could make sense to delete and then create (an -equilibrium). This is called normal ordering and is described below. You can +equilibrium). This is called normal ordering and is described below. You can override normal ordering in exceptional circumstances by making a promise in a class context and defining that class based on the outcome of another promise, or using the `depends_on` promise attribute. @@ -49,14 +49,14 @@ below. Before exact evaluation of promises takes place first command line parameters are read and all classes defined using `-D` parameter are set. Next, -environment detection takes place and hard classes are discovered. When +environment detection takes place and hard classes are discovered. When environment detection is complete all the persistent classes are loaded and a policy sanity check is performed using cf-promises. #### cf-promises policy validation step In this step policy is validated and `classes` and `vars` promises are -evaluated. Note that cached functions are executed here, and then again during +evaluated. Note that cached functions are executed here, and then again during the normal agent execution. Variables and classes resolved in this step do not persist into the following evaluation step, so all functions will run again during Agent pre-evaluation. @@ -80,7 +80,7 @@ The following steps are executed per-bundle for each file parsed, in this order: 1. if it's a common bundle, evaluate **vars** promises 2. if it's a common bundle, evaluate **classes** promises 3. evaluate **vars** promises -(for details see `PolicyResolve()` in the C code) + (for details see `PolicyResolve()` in the C code) This is done because classes placed in common bundles are global whereas classes placed in agent bundles are local (by default) to diff --git a/content/reference/language-concepts/promises.markdown b/content/reference/language-concepts/promises.markdown index 2ae8748c9..1cd21cd4b 100644 --- a/content/reference/language-concepts/promises.markdown +++ b/content/reference/language-concepts/promises.markdown @@ -104,25 +104,25 @@ participate in locking. Promise attributes have a type and a value. The type can be any of the [datatypes][datatypes] that are allowed for variables, and in addition -* Boolean - allowed input values are - * `"true"`/`"false"` - * `"on"`/`"off"` - * `"yes"`/`"no"` +- Boolean - allowed input values are + - `"true"`/`"false"` + - `"on"`/`"off"` + - `"yes"`/`"no"` -* `irange[min, max]` and `rrange[min, max]` - a range of integer or real +- `irange[min, max]` and `rrange[min, max]` - a range of integer or real values, created via the [`irange()`][irange] and [`rrange()`][rrange] functions -* `clist` - a list of classes or class expressions. Note that these - attributes can take both strings (which are evaluated as class expressions) - and functions that return type `class` +- `clist` - a list of classes or class expressions. Note that these + attributes can take both strings (which are evaluated as class expressions) + and functions that return type `class` -* Menu option - one value from a list of values +- Menu option - one value from a list of values -* [`body` *type*][bodies] - a complex set of +- [`body` _type_][bodies] - a complex set of attributes expressed in a separate, reusable block -* [`bundle` *type*][bundles] - a separate bundle +- [`bundle` _type_][bundles] - a separate bundle that is used as a sub-routine or a sub-set of promises **Note:** The language does not specifically disallow the use of the same diff --git a/content/reference/language-concepts/variables.markdown b/content/reference/language-concepts/variables.markdown index 7ab270d96..9d393a4a5 100644 --- a/content/reference/language-concepts/variables.markdown +++ b/content/reference/language-concepts/variables.markdown @@ -12,9 +12,9 @@ as a context when using variables outside of the bundle they are defined in. CFEngine variables have three high-level types: scalars, lists, and data containers. -* A scalar is a single value, -* a list is a collection of scalars. -* a data container is a lot like a JSON document, it can be a key-value map or an array or anything else allowed by the JSON standard with unlimited nesting. +- A scalar is a single value, +- a list is a collection of scalars. +- a data container is a lot like a JSON document, it can be a key-value map or an array or anything else allowed by the JSON standard with unlimited nesting. ## Scalar variables @@ -29,20 +29,20 @@ vars: "my_real" real => "567.89"; ``` -Integer constants may use suffixes to represent large numbers. The following +Integer constants may use suffixes to represent large numbers. The following suffixes can be used to create integer values for common powers of 1000. -* 'k' = value times 1000 -* 'm' = value times 1000^2 -* 'g' = value times 1000^3 +- 'k' = value times 1000 +- 'm' = value times 1000^2 +- 'g' = value times 1000^3 Since computing systems such as storage and memory are based on binary values, CFEngine also provide the following uppercase suffixes to create integer values for common powers of 1024. -* 'K' = value times 1024. -* 'M' = value times 1024^2 -* 'G' = value times 1024^3 +- 'K' = value times 1024. +- 'M' = value times 1024^2 +- 'G' = value times 1024^3 However, the values must have an integer numeric part (e.g. 1.5M is not allowed). @@ -52,11 +52,11 @@ In some contexts, `%` can be used a special suffix to denote percentages. Lastly, there is a reserved value which can be used to specify a parameter as having no limit at all. -* 'inf' = a constant representing an unlimited value. +- 'inf' = a constant representing an unlimited value. - ```inf``` is a special value that in the code corresponds to the magic number of ```999999999``` (nine nines). Thus any function that accepts a number, can accept inf without a problem. Keep in mind though that you can get a higher number if you set the upper limit manually, but that's almost never a problem. + `inf` is a special value that in the code corresponds to the magic number of `999999999` (nine nines). Thus any function that accepts a number, can accept inf without a problem. Keep in mind though that you can get a higher number if you set the upper limit manually, but that's almost never a problem. - For a few functions ```inf``` is being treated specially and truly means "there is no limit" instead of "nine nines limit". This is the case for the ```maxbytes``` parameter and applies to most read* functions. + For a few functions `inf` is being treated specially and truly means "there is no limit" instead of "nine nines limit". This is the case for the `maxbytes` parameter and applies to most read\* functions. CFEngine typing is mostly dynamic, and CFEngine will try to coerce string values into int and real types, and if it cannot it will report an error. @@ -84,7 +84,7 @@ be escaped. ### Scalar size limitations -At the moment, up to 4095 bytes can fit into a scalar variable. This +At the moment, up to 4095 bytes can fit into a scalar variable. This limitation may be removed in the future. If you try to expand strings in a variable or string context that add @@ -142,7 +142,7 @@ iterate over the values in the list. E.g. suppose we have local list variable the list. In some function calls, `listname` instead of `@(listname)` is -expected. See the specific function's documentation to be sure. +expected. See the specific function's documentation to be sure. ## Data container variables @@ -155,7 +155,7 @@ Data containers are obtained from functions that return `data` types, such as `readjson()` or `parsejson()`, `readyaml()` or `parseyaml()`, or from merging existing containers. -They can **NOT** be *modified*, once created, but they can be re-defined. +They can **NOT** be _modified_, once created, but they can be re-defined. Data containers do not have the size limitations of regular scalar variables. diff --git a/content/reference/macros.markdown b/content/reference/macros.markdown index 5c0482f3b..0fb77fe07 100644 --- a/content/reference/macros.markdown +++ b/content/reference/macros.markdown @@ -21,7 +21,7 @@ This applies to all version macros. ### Minimum version -The contained policy is only included if the version is greater than or equal to the specified version. +The contained policy is only included if the version is greater than or equal to the specified version. ```cf3 bundle agent extractor @@ -37,7 +37,7 @@ vars: "container" data => new_function_3_8(...); ### Maximum version -The contained policy is only included if the version is lower than or equal to the specified version. +The contained policy is only included if the version is lower than or equal to the specified version. **Example:** @@ -192,12 +192,12 @@ possibly incompatible versions. Currently available features are: -* `xml` -* `yaml` -* `curl` -* `pam` +- `xml` +- `yaml` +- `curl` +- `pam` **History:** -* This macro was introduced in CFEngine 3.8.0 -* `pam` feature was introduced in CFEngine 3.26.0 +- This macro was introduced in CFEngine 3.8.0 +- `pam` feature was introduced in CFEngine 3.26.0 diff --git a/content/reference/masterfiles-policy-framework/lib.markdown b/content/reference/masterfiles-policy-framework/lib.markdown index 3ff508b38..82534a9f7 100644 --- a/content/reference/masterfiles-policy-framework/lib.markdown +++ b/content/reference/masterfiles-policy-framework/lib.markdown @@ -10,6 +10,6 @@ patterns. This directories contents are expected to be found in the following locations: -* [`$(sys.libdir)`][sys#sys.libdir] +- [`$(sys.libdir)`][sys#sys.libdir] -* [`$(sys.local_libdir)`][sys#sys.local_libdir] (relative to the root of your policy inputs) +- [`$(sys.local_libdir)`][sys#sys.local_libdir] (relative to the root of your policy inputs) diff --git a/content/reference/masterfiles-policy-framework/modules-packages-vendored.markdown b/content/reference/masterfiles-policy-framework/modules-packages-vendored.markdown index d14fda5c7..ef9fb7f01 100644 --- a/content/reference/masterfiles-policy-framework/modules-packages-vendored.markdown +++ b/content/reference/masterfiles-policy-framework/modules-packages-vendored.markdown @@ -2,4 +2,5 @@ layout: default title: modules/packages/vendored/ --- + This directory tree is used for distributing package modules that are rendered into place with mustache. The modules found here are rendered into place if no plain copy is found in the parent directory. diff --git a/content/reference/masterfiles-policy-framework/modules-packages.markdown b/content/reference/masterfiles-policy-framework/modules-packages.markdown index ffb0baa79..8d2f8778f 100644 --- a/content/reference/masterfiles-policy-framework/modules-packages.markdown +++ b/content/reference/masterfiles-policy-framework/modules-packages.markdown @@ -2,6 +2,7 @@ layout: default title: modules/packages/ --- + This directory tree is used for distributing package modules. Files in this directory have an executable copy in `$(sys.workdir)/modules/packages/` and take precedence over modules in the vendored directory. diff --git a/content/reference/masterfiles-policy-framework/modules-promises.markdown b/content/reference/masterfiles-policy-framework/modules-promises.markdown index bc847ce73..6c46910a1 100644 --- a/content/reference/masterfiles-policy-framework/modules-promises.markdown +++ b/content/reference/masterfiles-policy-framework/modules-promises.markdown @@ -2,6 +2,7 @@ layout: default title: modules/promises/ --- + This directory tree is used for distributing promise modules and supporting libraries. Files in this directory have an executable copy in `$(sys.workdir)/modules/packages/` and take precedence over modules in the vendored directory. diff --git a/content/reference/masterfiles-policy-framework/modules.markdown b/content/reference/masterfiles-policy-framework/modules.markdown index c52a6129e..e4347811c 100644 --- a/content/reference/masterfiles-policy-framework/modules.markdown +++ b/content/reference/masterfiles-policy-framework/modules.markdown @@ -2,6 +2,7 @@ layout: default title: modules/ --- + This directory tree is used for distributing Modules. The [packages subtree][modules/packages/] is used for vendoring packages modules and the [promises sub-directory][modules/promises/] is used for promise modules, including the libraries used by promise modules. Distribute custom package modules by placing them in the packages directory. Modules placed in the root of the packages directory are copied into `$(sys.workdir)/modules/`. diff --git a/content/reference/masterfiles-policy-framework/standalone_self_upgrade.markdown b/content/reference/masterfiles-policy-framework/standalone_self_upgrade.markdown index 85cb57a9f..1b3131cf4 100644 --- a/content/reference/masterfiles-policy-framework/standalone_self_upgrade.markdown +++ b/content/reference/masterfiles-policy-framework/standalone_self_upgrade.markdown @@ -11,6 +11,6 @@ defined and the host is not seen to be running the desired version of the agent. The policy is designed for use with Enterprise packages, but can be customized for use with community packages. -*** +--- {{< CFEngine_library_include(standalone_self_upgrade) >}} diff --git a/content/reference/promise-types/_index.markdown b/content/reference/promise-types/_index.markdown index ac5ff2754..2f5f7645a 100644 --- a/content/reference/promise-types/_index.markdown +++ b/content/reference/promise-types/_index.markdown @@ -8,25 +8,25 @@ Within a bundle, the promise types are executed in a round-robin fashion in the following [normal order][Policy evaluation]. Which promise types are available depends on the [bundle][bundles] type: -| Promise type | common | agent | server | monitor | -|----------------|:------:|:-----:|:------:|:--------| -| [defaults][defaults] - a default value for bundle parameters | x | x | x | x | -| [classes][classes] - a class, representing a state of the system | x | x | x | x | -| [meta][meta] - information about promise bundles | x | x | x | x | -| [reports][reports] - report a message | x | x | x | x | -| [vars][vars] - a variable, representing a value | x | x | x | x | -| [commands][commands] - execute a command | | x | | | -| [databases][databases] - configure a database | | x | | | -| [files][files] - configure a file | | x | | | -| [packages][packages] - install a package | | x | | | -| [guest_environments][guest_environments] | | x | | | -| [methods][methods] - take on a whole bundle of other promises | | x | | | -| [processes][processes] - start or terminate processes | | x | | | -| [services][services] - manage services or define new abstractions | | x | | | -| [storage][storage] - verify attached storage | | x | | | -| [users][users] - add or remove users | | x | | | -| [access][access] - grant or deny access to file objects | | | x | | -| [roles][roles] - allow certain users to activate certain classes | | | x | | +| Promise type | common | agent | server | monitor | +| --------------------------------------------------------------------- | :----: | :---: | :----: | :------ | +| [defaults][defaults] - a default value for bundle parameters | x | x | x | x | +| [classes][classes] - a class, representing a state of the system | x | x | x | x | +| [meta][meta] - information about promise bundles | x | x | x | x | +| [reports][reports] - report a message | x | x | x | x | +| [vars][vars] - a variable, representing a value | x | x | x | x | +| [commands][commands] - execute a command | | x | | | +| [databases][databases] - configure a database | | x | | | +| [files][files] - configure a file | | x | | | +| [packages][packages] - install a package | | x | | | +| [guest_environments][guest_environments] | | x | | | +| [methods][methods] - take on a whole bundle of other promises | | x | | | +| [processes][processes] - start or terminate processes | | x | | | +| [services][services] - manage services or define new abstractions | | x | | | +| [storage][storage] - verify attached storage | | x | | | +| [users][users] - add or remove users | | x | | | +| [access][access] - grant or deny access to file objects | | | x | | +| [roles][roles] - allow certain users to activate certain classes | | | x | | | [measurements][measurements] - measure or sample data from the system | | | | x | See each promise type's reference documentation for detailed lists of available @@ -53,11 +53,11 @@ kept. **Allowed input range:** -* ```fix``` makes changes to move toward the desired state -* ```warn``` does not make changes, emits a warning level log message about non-compliance, raise repair_failed (not-kept) -* ```nop``` alias for warn +- `fix` makes changes to move toward the desired state +- `warn` does not make changes, emits a warning level log message about non-compliance, raise repair_failed (not-kept) +- `nop` alias for warn -**Default value:** ```fix``` +**Default value:** `fix` **Example:** @@ -72,7 +72,7 @@ Output: #### ifelapsed **Description:** The number of minutes before next allowed assessment of a -promise is set using `ifelapsed`. This overrides the global settings. Promises +promise is set using `ifelapsed`. This overrides the global settings. Promises which take a long time to verify should usually be protected with a long value for this parameter. @@ -102,15 +102,15 @@ body action example **Notes:** -* This is not a reliable way to control frequency over a long period of time. -* Locks provide simple but weak frequency control. -* Locks older than 4 weeks are automatically purged. +- This is not a reliable way to control frequency over a long period of time. +- Locks provide simple but weak frequency control. +- Locks older than 4 weeks are automatically purged. **See also:** [promise locking][Promises#Promise Locking], [ifelapsed in body agent control][cf-agent#ifelapsed], [`ifelapsed` and function caching][Functions#function caching] **History:** -* `ifelapsed => "0"` disables function caching for specific promise introduced in 3.19.0, 3.18.1 +- `ifelapsed => "0"` disables function caching for specific promise introduced in 3.19.0, 3.18.1 #### expireafter @@ -182,7 +182,9 @@ useful referent in a log message, indicating the origin of the message. In [CFEngine Enterprise](https://cfengine.com/product-overview/), promise handles make it easy to interpret report data. #### log_kept + #### log_repaired + #### log_failed **Description:** The names of files to which `log_string` will be saved @@ -203,12 +205,12 @@ syslog. This string should be the full path to a text file which will contain the log, or one of the following special values: -* `stdout` +- `stdout` Send the log message to the standard output, prefixed with an L: to indicate a log message. -* `udp_syslog` +- `udp_syslog` Log messages to [syslog_host][Components#syslog_host] as defined in body common control over UDP. Please note @@ -633,9 +635,9 @@ cancel (undefine) any of the listed classes so that they are no longer defined. **Notes:** -* Hard classes can **not** be undefined. If you try to undefine or cancel a hard +- Hard classes can **not** be undefined. If you try to undefine or cancel a hard class an error will be emitted, for example `error: You cannot cancel a - reserved hard class 'cfengine' in post-condition classes`. +reserved hard class 'cfengine' in post-condition classes`. **History:** This attribute was introduced in CFEngine version 3.0.4 (2010) @@ -665,9 +667,9 @@ defined. **Notes:** -* Hard classes can **not** be undefined. If you try to undefine or cancel a hard +- Hard classes can **not** be undefined. If you try to undefine or cancel a hard class an error will be emitted, for example `error: You cannot cancel a - reserved hard class 'cfengine' in post-condition classes`. +reserved hard class 'cfengine' in post-condition classes`. **History:** This attribute was introduced in CFEngine version 3.0.4 (2010) @@ -698,9 +700,9 @@ defined. **Notes:** -* Hard classes can **not** be undefined. If you try to undefine or cancel a hard +- Hard classes can **not** be undefined. If you try to undefine or cancel a hard class an error will be emitted, for example `error: You cannot cancel a - reserved hard class 'cfengine' in post-condition classes`. +reserved hard class 'cfengine' in post-condition classes`. **History:** This attribute was introduced in CFEngine version 3.0.4 (2010) @@ -710,9 +712,9 @@ defined. Currently, the attribute has impact on the following command-related promises: -* All promises of type `commands:` -* `files`-promises containing a `transformer`-attribute -* The package manager change command in `packages`-promises (e.g. the command +- All promises of type `commands:` +- `files`-promises containing a `transformer`-attribute +- The package manager change command in `packages`-promises (e.g. the command for add, remove, etc.) If none of the attributes `kept_returncodes`, `repaired_returncodes`, or @@ -761,9 +763,9 @@ compliance statistics. Currently, the attribute has impact on the following command-related promises: -* All promises of type `commands:` -* `files`-promises containing a `transformer`-attribute -* The package manager change command in `packages`-promises (e.g. the command +- All promises of type `commands:` +- `files`-promises containing a `transformer`-attribute +- The package manager change command in `packages`-promises (e.g. the command for add, remove, etc.) If none of the attributes `kept_returncodes`, `repaired_returncodes`, or @@ -813,9 +815,9 @@ a failed command-related promise. Currently, the attribute has impact on the following command-related promises: -* All promises of type `commands:` -* `files`-promises containing a `transformer`-attribute -* The package manager change command in `packages`-promises (e.g. the command +- All promises of type `commands:` +- `files`-promises containing a `transformer`-attribute +- The package manager change command in `packages`-promises (e.g. the command for add, remove, etc.) If none of the attributes `kept_returncodes`, `repaired_returncodes`, or @@ -1144,7 +1146,7 @@ Relevant CFEngine functions are: `classesmatching()`, `classmatch()`, `countclassesmatching()`, `getclassmetatags()`, `getvariablemetatags()`, `variablesmatching()`, `variablesmatching_as_data()`. Also see [meta promises][meta]: While "meta" attribute can be added to a promise of any type, there can also be promises of promise type "meta" added to any bundle. -If mention is made of "tags" on a *bundle*, what is actually meant is meta *promises* in that bundle. +If mention is made of "tags" on a _bundle_, what is actually meant is meta _promises_ in that bundle. (This is just a terminology point.) **Note:** When a variable is re-defined the associated meta tags are also re-defined. diff --git a/content/reference/promise-types/access.markdown b/content/reference/promise-types/access.markdown index bac9997cc..22f583dd0 100644 --- a/content/reference/promise-types/access.markdown +++ b/content/reference/promise-types/access.markdown @@ -107,7 +107,7 @@ first-come-first-served basis. Thus file objects (promisers) should be listed in order of most-specific file first. In this way, specific promises will override less specific ones. -**** +--- ## Attributes @@ -119,16 +119,16 @@ promises will override less specific ones. **Note:** The host trying to access the object is identified using a reverse DNS lookup on the connecting IP. This introduces latency for -*every* incoming connection. If possible, avoid this penalty by +_every_ incoming connection. If possible, avoid this penalty by leaving `admit_hostnames` empty and only specifying numeric addresses and subnets in `admit_ips`. -To admit an entire domain, start the string with a dot `.`. This +To admit an entire domain, start the string with a dot `.`. This includes every hostname ending with the domain, but not a machine named after the domain itself. For example, here we'll admit the entire domain `.cfengine.com` and -the host `www.cfengine3.com`. A machine named `cfengine.com` would be +the host `www.cfengine3.com`. A machine named `cfengine.com` would be refused access because it's not in the `cfengine.com` domain. ```cf3 @@ -148,7 +148,7 @@ access: **Description:** A list of IP addresses that should have access to the object. -Subnets are specified using CIDR notation. For example, here we'll +Subnets are specified using CIDR notation. For example, here we'll admit one host, then a subnet, then everyone: ```cf3 @@ -199,12 +199,12 @@ access: This overrides the grants in `admit_hostnames`, `admit_ips` and `admit_keys`. -To deny an entire domain, start the string with a dot `.`. This +To deny an entire domain, start the string with a dot `.`. This includes every hostname ending with the domain, but not a machine named after the domain itself. For example, here we'll deny the entire domain `.cfengine.com` and the -host `www.cfengine3.com`. A machine named `cfengine.com` would be +host `www.cfengine3.com`. A machine named `cfengine.com` would be allowed access (unless it's denied by other promises) because it's not in the `cfengine.com` domain. @@ -443,12 +443,12 @@ Here are the built-in `report_data_select` bodies `default_data_select_host()` a **History:** -* Introduced in Enterprise 3.5.0 +- Introduced in Enterprise 3.5.0 -* `metatags_exclude`, `metatags_include`, `promise_handle_exclude`, and +- `metatags_exclude`, `metatags_include`, `promise_handle_exclude`, and `promise_handle_include` body attributes added in 3.6.0. -* `classes_exclude`, `classes_include`, `promise_notkept_log_exclude`, +- `classes_exclude`, `classes_include`, `promise_notkept_log_exclude`, `promise_notkept_log_include`, `promise_repaired_log_exclude`, `promise_repaired_log_include`, `variables_exclude`, and `variables_include` body attributes removed in 3.6.0 @@ -647,7 +647,7 @@ bundle server my_access_rules() **History:** -- ```bundle``` `resource_type` added in 3.9.0 +- `bundle` `resource_type` added in 3.9.0 ### shortcut diff --git a/content/reference/promise-types/classes.markdown b/content/reference/promise-types/classes.markdown index 0fa8a2188..aeed83ee2 100644 --- a/content/reference/promise-types/classes.markdown +++ b/content/reference/promise-types/classes.markdown @@ -26,15 +26,14 @@ classes: {{< CFEngine_include_example(class-automatic-canonificiation.cf) >}} -- The term ```class``` and ```context``` are sometimes used interchangeably. +- The term `class` and `context` are sometimes used interchangeably. - The following attributes to make a complete promise. - - * and - * expression - * dist - * or - * not - * xor + - and + - expression + - dist + - or + - not + - xor If you omit all of them, the class is always defined (as if you said `expression => "any"`). @@ -68,7 +67,7 @@ bundle agent example } ``` -*** +--- ## Attributes @@ -144,22 +143,22 @@ change during execution. Expressions can be: -* class names, with or without a namespace +- class names, with or without a namespace -* the literals `true` (always defined) and `false` (never defined) that allow JSON booleans to be used inside expressions +- the literals `true` (always defined) and `false` (never defined) that allow JSON booleans to be used inside expressions -* the logical *and* operation, expressed as `a&b` or `a.b`, which is true if both `a` and `b` are true +- the logical _and_ operation, expressed as `a&b` or `a.b`, which is true if both `a` and `b` are true -* the logical *or* operation, expressed as `a|b`, which is true if either `a` or `b` are true +- the logical _or_ operation, expressed as `a|b`, which is true if either `a` or `b` are true -* the logical *not* operation, expressed as `!a`, which is true if `a` is not +- the logical _not_ operation, expressed as `!a`, which is true if `a` is not true. Note again here that `a` could **become** true during the execution. So if you have `"myclass" expression => "!x"` and `x` starts undefined but is defined later, you could have both `x` **and** `myclass` defined! -* parenthesis `(whatever)` which operate as expected to prioritize expression evaluation +- parenthesis `(whatever)` which operate as expected to prioritize expression evaluation -* the return value of a function that returns a class, such as `fileexists()` `and()` `userexists()` etc. +- the return value of a function that returns a class, such as `fileexists()` `and()` `userexists()` etc. **Type:** `class` diff --git a/content/reference/promise-types/commands.markdown b/content/reference/promise-types/commands.markdown index 4b9db6759..f075cdc96 100644 --- a/content/reference/promise-types/commands.markdown +++ b/content/reference/promise-types/commands.markdown @@ -57,6 +57,7 @@ commands: "\"/usr/bin/funny command name\" -a -b -c"; ``` + **Note:** Commands executed with CFEngine get the environment variables set in [`environment`][cf-agent#environment] in body agent control. If you want to set environment variables for an individual command you can prefix the command with @@ -78,7 +79,7 @@ bundle agent example detect the end of file condition). This occurs on POSIX.1 and SVR4 popen calls which use wait4. For some reason they fail to find and end-of-file for an exiting child process and go into a deadlock trying to read from an already -dead process. This leaves a zombie behind (the parent daemon process which +dead process. This leaves a zombie behind (the parent daemon process which forked and was supposed to exit) though the child continues. A way around this is to use a wrapper script which prints the line `cfengine-die` to STDOUT after restarting the process. This causes CFEngine to close the pipe forcibly and @@ -86,7 +87,7 @@ continue. **See also:** [Bundles and Bodies for commands in the stdlib][lib/commands.cf] -**** +--- ## Attributes @@ -160,8 +161,8 @@ So in the example above the command would be: **History:** -* Introduced in CFEngine 3.9.0. -* Fixed whitespace preservation when not using shell on non-Windows agents in 3.24.0 +- Introduced in CFEngine 3.9.0. +- Fixed whitespace preservation when not using shell on non-Windows agents in 3.24.0 **See also:** `args`, `join()`, `concat()`, `format()` @@ -195,7 +196,7 @@ exec_timeout => "60"; **Description:** Specifies whether or not to use a shell when executing the command. -The default is to *not* use a shell when executing commands. Use of a +The default is to _not_ use a shell when executing commands. Use of a shell has both resource and security consequences. A shell consumes an extra process and inherits environment variables, reads commands from files and performs other actions beyond the control of CFEngine. @@ -330,7 +331,7 @@ exec_timeout => "30"; } ``` -**See also:** [`body action expireafter`][Promise types#expireafter], [`body agent control expireafter`][cf-agent#expireafter], [`body executor control agent_expireafter`][cf-execd#agent_expireafter] +**See also:** [`body action expireafter`][Promise types#expireafter], [`body agent control expireafter`][cf-agent#expireafter], [`body executor control agent_expireafter`][cf-execd#agent_expireafter] #### chdir @@ -452,23 +453,23 @@ promises. Such a module may be written in any language. This attribute determines whether or not to expect the CFEngine module protocol. If true, the module protocol is supported for this command: -* lines which begin with a `^` are protocol extensions - * `^context=xyz` sets the module context to `xyz` instead of the default for any following definitions - * `^meta=a,b,c` sets the class and variable tags for any following definitions to `a`, `b`, and `c` - * `^persistence=10` sets any following classes to persist for 10 minutes (use 0 to reset) - * `^persistence=0` sets any following classes to have no persistence (this is the default) -* lines which begin with a `+` are treated as classes to be defined (like -D). **NOTE:** classes are defined with the [`namespace` scope][Classes and decisions]. -* lines which begin with a `-` are treated as classes to be undefined (like -N) -* lines which begin with `=` are scalar variables to be defined -* lines which begin with `=` and include `[]` are array variables to be defined -* lines which begin with `@` are lists. -* lines which begin with `%` are `data` containers. The value needs to be valid JSON and will be decoded. +- lines which begin with a `^` are protocol extensions + - `^context=xyz` sets the module context to `xyz` instead of the default for any following definitions + - `^meta=a,b,c` sets the class and variable tags for any following definitions to `a`, `b`, and `c` + - `^persistence=10` sets any following classes to persist for 10 minutes (use 0 to reset) + - `^persistence=0` sets any following classes to have no persistence (this is the default) +- lines which begin with a `+` are treated as classes to be defined (like -D). **NOTE:** classes are defined with the [`namespace` scope][Classes and decisions]. +- lines which begin with a `-` are treated as classes to be undefined (like -N) +- lines which begin with `=` are scalar variables to be defined +- lines which begin with `=` and include `[]` are array variables to be defined +- lines which begin with `@` are lists. +- lines which begin with `%` are `data` containers. The value needs to be valid JSON and will be decoded. These variables end up in a context that has the same name as the module, unless the `^context` extension is used. **NOTE**: All variables and classes defined by the module protocol are defined -in the ```default``` namespace. It is not possible to define variables and +in the `default` namespace. It is not possible to define variables and classes in any other namespace. Protocol extensions ( lines that start with `^` ) apply until they are explicitly reset, or until the end of the modules execution. @@ -480,8 +481,8 @@ Any other lines of output are cited by `cf-agent` as being erroneous, so you should normally make your module completely silent. **WARNING:** Variables defined by the module protocol are currently limited to -alphanumeric characters and ```_```, ```.```, ```-```, ```[```, ```]```, ```@``` and -```/```. +alphanumeric characters and `_`, `.`, `-`, `[`, `]`, `@` and +`/`. **Type:** [`boolean`][boolean] @@ -556,7 +557,7 @@ if (special-condition) ``` If your module is simple and is best expressed as a shell command, then we -suggest that you *expose* the class being defined in the command being +suggest that you _expose_ the class being defined in the command being executed (making it easier to see what classes are used when reading the promises file). For example, the promises could read as follows (the two `echo` commands are to ensure that the shell always exits with a successful @@ -599,5 +600,5 @@ arguments, just as a regular command does. **History:** -- ```@``` allowed in variables (intended for keys in classic array) 3.15.0, 3.12.3, 3.10.7 (2019) -- ```/``` allowed in variables (intended for keys in classic array) 3.14.0, 3.12.2, 3.10.6 (2019) +- `@` allowed in variables (intended for keys in classic array) 3.15.0, 3.12.3, 3.10.7 (2019) +- `/` allowed in variables (intended for keys in classic array) 3.14.0, 3.12.2, 3.10.6 (2019) diff --git a/content/reference/promise-types/custom.markdown b/content/reference/promise-types/custom.markdown index fe45c2315..c23fdd2d7 100644 --- a/content/reference/promise-types/custom.markdown +++ b/content/reference/promise-types/custom.markdown @@ -14,10 +14,10 @@ This documentation article provides a complete and detailed specification. It includes how to use them, how to implement them using modules, how the protocol works, etc. If you are interested in shorter tutorials, there are a few different ones available: -* [Introducing CFEngine Custom Promise types - Installation and usage](https://cfengine.com/blog/2020/introducing-cfengine-custom-promise-types/) -* [How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) -* [How to implement CFEngine custom promise types in bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) -* [Custom Promise outcomes in Mission Portal](https://cfengine.com/blog/2021/custom-promise-outcomes-in-mission-portal/) +- [Introducing CFEngine Custom Promise types - Installation and usage](https://cfengine.com/blog/2020/introducing-cfengine-custom-promise-types/) +- [How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) +- [How to implement CFEngine custom promise types in bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) +- [Custom Promise outcomes in Mission Portal](https://cfengine.com/blog/2021/custom-promise-outcomes-in-mission-portal/) ## Using custom promise types @@ -63,36 +63,36 @@ The agent evaluates these, and decides whether to request evaluation from the mo These attributes are handled by the agent, and cannot be used inside promise modules: -* `if` / `ifvarclass` -* `unless` -* `action` (body for `ifelapsed`, `expireafter`, etc.) - * `action_policy`, if not default, will be sent to the module, for dry-run/no-changes functionality -* `comment` -* `depends_on` -* `handle` -* [`meta`][Promise types#meta] -* `with` -* `classes` +- `if` / `ifvarclass` +- `unless` +- `action` (body for `ifelapsed`, `expireafter`, etc.) + - `action_policy`, if not default, will be sent to the module, for dry-run/no-changes functionality +- `comment` +- `depends_on` +- `handle` +- [`meta`][Promise types#meta] +- `with` +- `classes` In an early iteration, the agent will emit errors for any of these which are not implemented yet, if you try to use them. Due to the implementation details, the following attributes from the `classes` body also cannot be used inside promise modules: -* `classes_name` -* `scope` -* `promise_repaired` -* `repair_failed` -* `repair_denied` -* `repair_timeout` -* `promise_kept` -* `cancel_repaired` -* `cancel_kept` -* `cancel_notkept` -* `kept_returncodes` -* `repaired_returncodes` -* `failed_returncodes` -* `persist_time` -* `timer_policy` +- `classes_name` +- `scope` +- `promise_repaired` +- `repair_failed` +- `repair_denied` +- `repair_timeout` +- `promise_kept` +- `cancel_repaired` +- `cancel_kept` +- `cancel_notkept` +- `kept_returncodes` +- `repaired_returncodes` +- `failed_returncodes` +- `persist_time` +- `timer_policy` ### Evaluation passes and normal order @@ -161,20 +161,20 @@ https://github.com/cfengine/core/blob/master/CONTRIBUTING.md#log-levels In short, when writing a promise module, these log levels should be used: -* `critical` - Serious errors in protocol or module itself (not in policy) -* `error` - Errors when validating / evaluating a promise, including syntax errors and promise not kept -* `warning` - The promise did not fail, but there is something the user (policy writer) should probably fix. Some examples: - * Policy relies on deprecated behavior/syntax which will change - * Policy uses demo / unsafe options which should be avoided in a production environment -* `notice` - Unusual events which you want to notify the user about - * Most promise types won't need this - usually `info` or `warning` is more appropriate - * Useful for events which happen rarely and are not the result of a promise, for example: - * New credentials detected - * New host bootstrapped - * The module made a change to the system for itself to work (database initialized, user created) -* `info` - Changes made to the system (usually 1 per repaired promise, more if the promise made multiple different changes to the system) -* `verbose` - Human understandable detailed information about promise evaluation -* `debug` - Programmer-level information that is only useful for CFEngine developers or module developers +- `critical` - Serious errors in protocol or module itself (not in policy) +- `error` - Errors when validating / evaluating a promise, including syntax errors and promise not kept +- `warning` - The promise did not fail, but there is something the user (policy writer) should probably fix. Some examples: + - Policy relies on deprecated behavior/syntax which will change + - Policy uses demo / unsafe options which should be avoided in a production environment +- `notice` - Unusual events which you want to notify the user about + - Most promise types won't need this - usually `info` or `warning` is more appropriate + - Useful for events which happen rarely and are not the result of a promise, for example: + - New credentials detected + - New host bootstrapped + - The module made a change to the system for itself to work (database initialized, user created) +- `info` - Changes made to the system (usually 1 per repaired promise, more if the promise made multiple different changes to the system) +- `verbose` - Human understandable detailed information about promise evaluation +- `debug` - Programmer-level information that is only useful for CFEngine developers or module developers Note that all log levels, except for `debug`, should be friendly to non-developers, and not include programmer's details (such as protocol messages, source code references, function names, etc.). @@ -183,25 +183,25 @@ Note that all log levels, except for `debug`, should be friendly to non-develope Each operation performed by the module, sends a result back to the agent. The possible results are as follows: -* Shared between operations: - * `error` - an unexpected error occured in the module or protocol, indicating a bug in CFEngine or the promise module - * Should be explained by a `critical` level log message -* Promise validation: - * `valid` - No problems with the data or data types in promise - * `invalid` - There are problems with the promise data or data types - * Should be explained by an `error` level log message -* Promise evaluation: - * The module should assume the promise has already been validated. - * It does not need to validate the promise again, and should **not** return `valid` / `invalid`. - * `kept` - promise satisfied already, no change made - * `repaired` - promise not satisfied before, but fixed now - * The change should be explained in a `info` level log message - * `not_kept` - promise not satisfied before, and could not be fixed - * Should be explained by an `error` level log message -* Teminate: - * `success` - Module succesfully terminated without errors - * `failure` - There were problems when trying to clean up / terminate - * Should be explained by a `critical` level log message +- Shared between operations: + - `error` - an unexpected error occured in the module or protocol, indicating a bug in CFEngine or the promise module + - Should be explained by a `critical` level log message +- Promise validation: + - `valid` - No problems with the data or data types in promise + - `invalid` - There are problems with the promise data or data types + - Should be explained by an `error` level log message +- Promise evaluation: + - The module should assume the promise has already been validated. + - It does not need to validate the promise again, and should **not** return `valid` / `invalid`. + - `kept` - promise satisfied already, no change made + - `repaired` - promise not satisfied before, but fixed now + - The change should be explained in a `info` level log message + - `not_kept` - promise not satisfied before, and could not be fixed + - Should be explained by an `error` level log message +- Teminate: + - `success` - Module succesfully terminated without errors + - `failure` - There were problems when trying to clean up / terminate + - Should be explained by a `critical` level log message Built-in CFEngine promises may have multiple outcomes when evaluated. For the sake of simplicity, custom promises may only have 1 outcome, logic should be as follows: @@ -224,16 +224,16 @@ When a promise module starts, the agent sends a protocol header (single line), f The header sent by cf-agent consists of 3 space-separated parts: -* Name of program - Example: `cf-agent` -* CFEngine version - Example: `3.16.0` -* Highest supported protocol version - Example: `v1` +- Name of program - Example: `cf-agent` +- CFEngine version - Example: `3.16.0` +- Highest supported protocol version - Example: `v1` The header response sent by the module consists of 4 or more space separated parts: -* Module name - Example: `git_promise_module` -* Module version - Example: `0.0.1` -* Requested protocol version - Example: `v1` -* Rest of line: [Feature flags](#features) separated by spaces. At least `json_based` or +- Module name - Example: `git_promise_module` +- Module version - Example: `0.0.1` +- Requested protocol version - Example: `v1` +- Rest of line: [Feature flags](#features) separated by spaces. At least `json_based` or `line_based` is required - Example: `json_based action_policy` The header has the same syntax regardless of protocol (It is used to determine protocol). @@ -314,14 +314,14 @@ header. Following are the currently recognized features supported by cf-agent. ##### Action policy -The *Action policy* feature, advertised as supported by the `action_policy` feature flag, indicates +The _Action policy_ feature, advertised as supported by the `action_policy` feature flag, indicates that the module can properly handle the action policy mechanism which allows user to specify that promises should only check the state of the system and produce warnings in case of mismatch instead of actually repairing the state. When supported by the module, the cf-agent will allow use of the promises handled by the module with: -* the `action_policy => "warn"` promise attribute and/or -* in one of the evaluation modes that disable making changes: `--dry-run` and `--simulate`. +- the `action_policy => "warn"` promise attribute and/or +- in one of the evaluation modes that disable making changes: `--dry-run` and `--simulate`. In all the above cases, the `action_policy` attribute with the value `"warn"` is sent to the module as part of the request. There is currently no differentiation between the cases. **If the module @@ -330,16 +330,16 @@ is that it would be unsafe to evaluate such promises in the above cases because make changes to the system while the user requested no changes to be made and only warnings to be produced instead. -The implementation of the *Action policy* feature must ensure that if the `action_policy` attribute +The implementation of the _Action policy_ feature must ensure that if the `action_policy` attribute is sent by cf-agent with the value `"warn"` then either the state of the system: -* is as described by the promise in which case the result is `kept` with only `debug` or `verbose` +- is as described by the promise in which case the result is `kept` with only `debug` or `verbose` messages returned by the module, or -* would require changes to be made in which case the result is `not_kept` with log messages with the +- would require changes to be made in which case the result is `not_kept` with log messages with the log level `warning` returned by the module, **but no changes are made on the system**. -A common pattern for warnings about changes that should be made is *"Should ACTION ON SOMETHING, but -only warnings promised"* with the *ACTION ON SOMETHING* part describing what should be done based on +A common pattern for warnings about changes that should be made is _"Should ACTION ON SOMETHING, but +only warnings promised"_ with the _ACTION ON SOMETHING_ part describing what should be done based on the promiser and other attributes, for example: ``` @@ -348,7 +348,7 @@ warning: Should update file '/tmp/test' with content 'Hello,world!', but only wa **History:** -* 3.21.0, 3.18.3 support in custom promise types introduced. +- 3.21.0, 3.18.3 support in custom promise types introduced. #### JSON protocol @@ -359,8 +359,8 @@ Protocol messages are separated by empty lines (double newline). The headers (request and response) are not JSON, but a sequence of space-separated values. All messages sent by cf-agent and the promise module are single line JSON-data, except: -* Headers (both from cf-agent and promise module) are not JSON. -* JSON responses sent from promise module may optionally be preceeded by log messages, as explained below. +- Headers (both from cf-agent and promise module) are not JSON. +- JSON responses sent from promise module may optionally be preceeded by log messages, as explained below. Within strings in the JSON data, newline characters must be escaped (`\n`). This is not strictly required by the JSON spec, but most implementations do this anyway. @@ -528,7 +528,7 @@ This enables the agent to filter the log messages based on log level, and also p See these tutorials / blog posts, for more examples or inspiration: -* [Introducing CFEngine Custom Promise types - Installation and usage](https://cfengine.com/blog/2020/introducing-cfengine-custom-promise-types/) -* [How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) -* [How to implement CFEngine Custom Promise types in Bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) -* [Custom Promise outcomes in Mission Portal](https://cfengine.com/blog/2021/custom-promise-outcomes-in-mission-portal/) +- [Introducing CFEngine Custom Promise types - Installation and usage](https://cfengine.com/blog/2020/introducing-cfengine-custom-promise-types/) +- [How to implement CFEngine Custom Promise types in Python](https://cfengine.com/blog/2020/how-to-implement-cfengine-custom-promise-types-in-python/) +- [How to implement CFEngine Custom Promise types in Bash](https://cfengine.com/blog/2021/how-to-implement-cfengine-custom-promise-types-in-bash/) +- [Custom Promise outcomes in Mission Portal](https://cfengine.com/blog/2021/custom-promise-outcomes-in-mission-portal/) diff --git a/content/reference/promise-types/databases.markdown b/content/reference/promise-types/databases.markdown index d9331938c..63e90c855 100644 --- a/content/reference/promise-types/databases.markdown +++ b/content/reference/promise-types/databases.markdown @@ -23,24 +23,24 @@ not a recommended task for CFEngine. There are three kinds of database supported by CFEngine: -* *LDAP - The Lightweight Directory Access Protocol* +- _LDAP - The Lightweight Directory Access Protocol_ - A hierarchical network database primarily for reading simple schema (Only - CFEngine Enterprise). + A hierarchical network database primarily for reading simple schema (Only + CFEngine Enterprise). -* *SQL - Structured Query Language* +- _SQL - Structured Query Language_ - A number of relational databases (currently supported: MySQL, Postgres for - reading and writing complex data. + A number of relational databases (currently supported: MySQL, Postgres for + reading and writing complex data. - **WARNING:** Neither MySQL/MariaDB or PostgreSQL support is built into the - default binaries. If you wish to use this functionality you must compile the - agent with support. + **WARNING:** Neither MySQL/MariaDB or PostgreSQL support is built into the + default binaries. If you wish to use this functionality you must compile the + agent with support. -* *Registry - Microsoft Registry* +- _Registry - Microsoft Registry_ - An embedded database for interfacing with system values in Microsoft - Windows (Only CFEngine Enterprise) + An embedded database for interfacing with system values in Microsoft + Windows (Only CFEngine Enterprise) In addition, CFEngine uses a variety of embedded databases for its own internals. @@ -141,7 +141,7 @@ Windows registry for instance. Entity-relation databases do not normally present tables in this way, but no harm is done in representing them as a hierarchy of depth 1. -*** +--- ## Attributes @@ -195,6 +195,7 @@ A blank value is equal to localhost. **Allowed input range:** (arbitrary string) **Example:** + ```cf3 db_server_host => "sqlserv.example.org"; ``` @@ -366,7 +367,7 @@ data-value pairs. The currently supported types (the middle field) for the Windows registry are `REG_SZ` (string), `REG_EXPAND_SZ` (expandable string) and `REG_DWORD` (double word). -If a column value has a comma you can escape the comma with backslash ```\,```. +If a column value has a comma you can escape the comma with backslash `\,`. ```cf3 bundle agent main diff --git a/content/reference/promise-types/defaults.markdown b/content/reference/promise-types/defaults.markdown index 8b74c97c1..883aa056c 100644 --- a/content/reference/promise-types/defaults.markdown +++ b/content/reference/promise-types/defaults.markdown @@ -84,7 +84,7 @@ reports: } ``` -*** +--- ## Attributes diff --git a/content/reference/promise-types/files/_index.markdown b/content/reference/promise-types/files/_index.markdown index 7dc591e03..552fedf23 100644 --- a/content/reference/promise-types/files/_index.markdown +++ b/content/reference/promise-types/files/_index.markdown @@ -178,17 +178,17 @@ one or more matched base-paths as shown in the example above. CFEngine allows regular expressions within filenames, but only after first doing some sanity checking to prevent some readily avoidable problems. The biggest rule you need to know about filenames and regular -expressions is that *all* regular expressions in filenames are bounded +expressions is that _all_ regular expressions in filenames are bounded by directory separators, and that each component expression is anchored between the directory separators. In other words, CFEngine splits up any file paths into its component parts, and then it evaluates any regular expressions at a component-level. What this means is that the path `/tmp/gar.*` will only match filenames -like `/tmp/gar`, `/tmp/garbage` and `/tmp/garden`. It will *not* match +like `/tmp/gar`, `/tmp/garbage` and `/tmp/garden`. It will _not_ match filename like `/tmp/gar/baz`; because even though the `.*` in a regular expression means "zero or more of any character", CFEngine restricts -that to mean "zero or more of any character *in a path component*". +that to mean "zero or more of any character _in a path component_". Correspondingly, CFEngine also restricts where you can use the `/` character. For example, you cannot use it in a character class like @@ -206,7 +206,7 @@ as `/tmp/abc/something` or `/tmp/xyzzy/something`. However, even though the pattern `.*` means "zero or more of any character (except /)", CFEngine matches files bounded by directory separators. So even though the pathname `/tmp//something` is technically the same as the pathname -`/tmp/something`, the regular expression `/tmp/.*/something` will *not* +`/tmp/something`, the regular expression `/tmp/.*/something` will _not_ match on the case of `/tmp//something` (or `/tmp/something`). ### Promises involving regular expressions @@ -233,9 +233,10 @@ files: body classes if_ok(x) { - promise_repaired => { "$(x)" }; +promise_repaired => { "$(x)" }; promise_kept => { "$(x)" }; } + @@ -252,15 +253,16 @@ bundle agent foobaz body file_select gars { -leaf_name => { "gar.*" }; +leaf_name => { "gar.\*" }; file_result => "leaf_name"; } body classes if_ok(x) { - promise_repaired => { "$(x)" }; +promise_repaired => { "$(x)" }; promise_kept => { "$(x)" }; } + @@ -269,26 +271,26 @@ In the first example, when the configuration containing this promise is first executed, any file starting with "gar" that exists in the `/tmp` directory will be removed, and the done class will be set. However, when the configuration is executed a second time, the pattern `/tmp/gar.*` -will not match any files, and that promise will not even be *attempted* -(and, consequently the done class will *not* be set). +will not match any files, and that promise will not even be _attempted_ +(and, consequently the done class will _not_ be set). In the second example, when the configuration containing this promise is first executed, any file starting with "gar" that exists in the `/tmp` directory will also be removed, and the done class will also be set. The second time the configuration is executed, however, the promise on the `/tmp` directory will still be executed (because `/tmp` of course still -exists), and the done class *will* be set, because all files matching +exists), and the done class _will_ be set, because all files matching the `file_select` attribute have been deleted from that directory. ### Local and remote searches There are two distinct kinds of depth search: -* A local search over promiser agents. -* A remote search over provider agents. +- A local search over promiser agents. +- A remote search over provider agents. -When we are *copying* or *linking* to a file source, it is the search -over the *remote* source that drives the content of a promise (the +When we are _copying_ or _linking_ to a file source, it is the search +over the _remote_ source that drives the content of a promise (the promise is a promise to use what the remote source provides). In general, the sources are on a different device to the images that make the promises. For all other promises, we search over existing local @@ -312,7 +314,7 @@ alter such a socket. This is a known issue, documented in [CFE-1782](https://northerntech.atlassian.net/browse/CFE-1782), and [CFE-1830](https://northerntech.atlassian.net/browse/CFE-1830). -*** +--- ## Attributes @@ -350,122 +352,121 @@ aces = { }; ``` -* `user` +- `user` - A valid username identifier for the system and cannot be empty. However, - `user` can be set to `*` as a synonym for the entity that owns the file - system object (e.g. `user:*:r`). + A valid username identifier for the system and cannot be empty. However, + `user` can be set to `*` as a synonym for the entity that owns the file + system object (e.g. `user:*:r`). - **Notes:** + **Notes:** * The user id is not a valid alternative. * This ACL is **required** when `acl_method` is set to `overwrite`. -* `uid` +- `uid` - A valid user identifier for the system and cannot be empty. However, `uid` - can be set to `*` as a synonym for the entity that owns the file system - object (e.g. `user:*:r`). + A valid user identifier for the system and cannot be empty. However, `uid` + can be set to `*` as a synonym for the entity that owns the file system + object (e.g. `user:*:r`). - **Note:** The username is not a valid alternative. + **Note:** The username is not a valid alternative. -* `group` +- `group` - A valid group identifier for the system and cannot be empty. However, - `group` can be set to `*` as a synonym for the group that owns the POSIX - file system object (`group:*:rwx`). + A valid group identifier for the system and cannot be empty. However, + `group` can be set to `*` as a synonym for the group that owns the POSIX + file system object (`group:*:rwx`). - **Notes:** + **Notes:** * The group id is not a valid alternative. * This ACL is **required** when `acl_method` is set to `overwrite`. -* `gid` +- `gid` - A valid group identifier for the system and cannot be empty. However, in - some ACL types, `gid` can be set to `*` to indicate a special group (e.g. in - POSIX this refers to the file group). + A valid group identifier for the system and cannot be empty. However, in + some ACL types, `gid` can be set to `*` to indicate a special group (e.g. in + POSIX this refers to the file group). - **Note:** The group name is not a valid alternative. + **Note:** The group name is not a valid alternative. -* `all` +- `all` - Indicates that the line applies to every user. + Indicates that the line applies to every user. - **Note:** This ACL is **required** when `acl_method` is set to `overwrite`. + **Note:** This ACL is **required** when `acl_method` is set to `overwrite`. -* `mask` +- `mask` - A valid mask identifier (e.g. `mask:rwx` ). In essence the mask is an upper - bound of the permissions that any entry in the group class will grant. When - `acl_method` is `overwrite` if mask is not supplied, it will default to - `mask:rwx`). + A valid mask identifier (e.g. `mask:rwx` ). In essence the mask is an upper + bound of the permissions that any entry in the group class will grant. When + `acl_method` is `overwrite` if mask is not supplied, it will default to + `mask:rwx`). -* `mode` +- `mode` - One or more strings `op`|`perms`|(`nperms`); a concatenation of `op`, - `perms` and optionally (`nperms`) separated with commas (e.g. `+rx,-w(s)` ). - `mode` is parsed from left to right. + One or more strings `op`|`perms`|(`nperms`); a concatenation of `op`, + `perms` and optionally (`nperms`) separated with commas (e.g. `+rx,-w(s)` ). + `mode` is parsed from left to right. -* `op` +- `op` - Specifies the operation on any existing permissions, if the defined ACE - already exists. `op` can be =, empty, + or -. = or empty sets the - permissions to the ACE as stated. + adds and - removes the permissions from - any existing ACE. + Specifies the operation on any existing permissions, if the defined ACE + already exists. `op` can be =, empty, + or -. = or empty sets the + permissions to the ACE as stated. + adds and - removes the permissions from + any existing ACE. -* `nperms` (optional) +- `nperms` (optional) - Specifies file system specific (native) permissions. Only valid if - `acl_type` is defined and will only be enforced if the file object is - stored on a file system supporting this ACL type. For - example, `nperms` will be ignored if `acl_type:``ntfs` and the object is - stored on a file system not supporting NTFS ACLs. Valid values for `nperms` - varies with different ACL types. When `acl_type` is set to `ntfs`, the - valid flags and their mappings is as follows: + Specifies file system specific (native) permissions. Only valid if + `acl_type` is defined and will only be enforced if the file object is + stored on a file system supporting this ACL type. For + example, `nperms` will be ignored if `acl_type:``ntfs` and the object is + stored on a file system not supporting NTFS ACLs. Valid values for `nperms` + varies with different ACL types. When `acl_type` is set to `ntfs`, the + valid flags and their mappings is as follows: - | CFEngine nperm flag | NTFS Special Permission | - |:----:|-------------| - | x | Execute File / Traverse Folder | - | r | Read Data / List Folder | - | t | Read Attributes | - | T | Read Extended Attributes | - | w | Write Data / Create Files | - | a | Append Data / Create Folders | - | b | Write Attributes | - | B | Write Extended Attributes | - | D | Delete Sub-folders and Files | - | d | Delete | - | p | Read Permissions | - | c | Change Permissions | - | o | Take Ownership | + | CFEngine nperm flag | NTFS Special Permission | + | :-----------------: | ------------------------------ | + | x | Execute File / Traverse Folder | + | r | Read Data / List Folder | + | t | Read Attributes | + | T | Read Extended Attributes | + | w | Write Data / Create Files | + | a | Append Data / Create Folders | + | b | Write Attributes | + | B | Write Extended Attributes | + | D | Delete Sub-folders and Files | + | d | Delete | + | p | Read Permissions | + | c | Change Permissions | + | o | Take Ownership | -* `perm_type` (optional) +- `perm_type` (optional) - Can be set to either `allow` or `deny`, and defaults to `allow`. `deny` is - only valid if `acl_type` is set to an ACL type that support deny - permissions. A `deny` ACE will only be enforced if the file object is stored - on a file system supporting the acl type set in `acl_type`. + Can be set to either `allow` or `deny`, and defaults to `allow`. `deny` is + only valid if `acl_type` is set to an ACL type that support deny + permissions. A `deny` ACE will only be enforced if the file object is stored + on a file system supporting the acl type set in `acl_type`. -* `gperms` (generic permissions) +- `gperms` (generic permissions) - A concatenation of zero or more of the characters shown in the table below. If - left empty, none of the permissions are set. + A concatenation of zero or more of the characters shown in the table below. If + left empty, none of the permissions are set. - | Flag | Description | Semantics on file | Semantics on directory | - |:----:|-------------|-------------------|------------------------| - | r | Read | Read data, permissions, attributes | Read directory contents, permissions, attributes | - | w | Write | Write data | Create, delete, rename subobjects | - | x | Execute | Execute file | Access subobjects | + | Flag | Description | Semantics on file | Semantics on directory | + | :--: | ----------- | ---------------------------------- | ------------------------------------------------ | + | r | Read | Read data, permissions, attributes | Read directory contents, permissions, attributes | + | w | Write | Write data | Create, delete, rename subobjects | + | x | Execute | Execute file | Access subobjects | - **Notes** + **Notes** + - The `r` permission is not necessary to read an object's permissions and + attributes in all file systems. For example, in POSIX, having `x` on its + containing directory is sufficient. - * The `r` permission is not necessary to read an object's permissions and - attributes in all file systems. For example, in POSIX, having `x` on its - containing directory is sufficient. - - * Capital `X` which is supported by the ```setfacl``` command is not - supported by the acl library, and thus not supported by the acl body. + - Capital `X` which is supported by the `setfacl` command is not + supported by the acl library, and thus not supported by the acl body. **Example:** @@ -805,7 +806,7 @@ servers => { "primary.example.org", "secondary.example.org", #### collapse_destination_dir -**Description:** Use `collapse_destination_dir` to flatten the directory hierarchy during copy. All the files will end up in the root destination directory. +**Description:** Use `collapse_destination_dir` to flatten the directory hierarchy during copy. All the files will end up in the root destination directory. Under normal operations, recursive copies cause CFEngine to track subdirectories of files. So, for instance, if we copy recursively from src to @@ -844,28 +845,28 @@ comparison can be used. **Allowed input range:** -* `mtime` +- `mtime` CFEngine copies the file if the modification time of the source file is more recent than that of the promised file -* `ctime` +- `ctime` CFEngine copies the file if the creation time of the source file is more recent than that of the promised file -* `atime` +- `atime` CFEngine copies the file if the modification time or creation time of the source file is more recent than that of the promised file. If the times are equal, a byte-for-bye comparison is done on the files to determine if it needs to be copied. -* `exists` +- `exists` CFEngine copies the file if the promised file does not already exist. -* `binary` +- `binary` CFEngine copies the file if they are both plain files and a byte-for-byte comparison determines that they are different. If both @@ -874,7 +875,7 @@ are not plain files, CFEngine reverts to comparing the `mtime` and (e.g. network copy), then `hash` is used instead to reduce network bandwidth. -* `hash` +- `hash` CFEngine copies the file if they are both plain files and a message digest comparison indicates that the files are different. In @@ -883,7 +884,7 @@ used as a message digest hash to conform with FIPS; in older Enterprise versions of CFEngine and all Community versions, MD5 is used. -* `digest` a synonym for `hash` +- `digest` a synonym for `hash` **Default value:** mtime or ctime differs @@ -925,7 +926,7 @@ body copy_from example } ``` -**See also:** [Common body attributes][Promise types#Common body attributes], [`default_repository` in ```body agent control```][cf-agent#default_repository], [`edit_backup` in ```body edit_defaults```][files#edit_backup] +**See also:** [Common body attributes][Promise types#Common body attributes], [`default_repository` in `body agent control`][cf-agent#default_repository], [`edit_backup` in `body edit_defaults`][files#edit_backup] #### encrypt @@ -958,7 +959,7 @@ noop as the entire session is encrypted. #### check_root **Description:** The `check_root` menu option policy checks permissions on the -root directory when copying files recursively by depth\_search. +root directory when copying files recursively by depth_search. This flag determines whether the permissions of the root directory should be set from the root of the source. The default is to check only copied file @@ -1081,7 +1082,7 @@ unpredictable. However, hard links are the only supported type by Windows. Note that symlink is synonymous with absolute links, which are different from relative links. Although all of these are symbolic links, the nomenclature here is defined such that symlink and absolute are equivalent. When verifying -a link, choosing 'relative' means that the link *must* be relative to the +a link, choosing 'relative' means that the link _must_ be relative to the source, so relative and absolute links are mutually exclusive. **Type:** (menu option) @@ -1311,7 +1312,7 @@ timeout => "10"; **Notes:** -* `cf-serverd` will time out any transfer that takes longer than 10 minutes +- `cf-serverd` will time out any transfer that takes longer than 10 minutes (this is not currently tunable). #### trustkey @@ -1412,7 +1413,7 @@ like `edit_line`, `edit_xml`, `edit_template` or `edit_template_string`. Directories are created by using the `/.` to signify a directory type. Note that, if no permissions are specified, mode 600 is chosen for a file, and mode 755 is chosen for a directory. If you cannot accept these -defaults, you *should* specify permissions. +defaults, you _should_ specify permissions. Note that technically, `/.` is a regular expression. However, it is used as a special case meaning "directory". See **filenames and regular @@ -1446,7 +1447,7 @@ if the `create` attribute is explicitly used. **History:** -* 3.20.0 Changed default from `false` to `true` for cases of full file management ( e.g. when `template_method` is `mustache`, `inline_mustache` or `cfengine`, or when the `content` or `copy_from` attributes are used ). +- 3.20.0 Changed default from `false` to `true` for cases of full file management ( e.g. when `template_method` is `mustache`, `inline_mustache` or `cfengine`, or when the `content` or `copy_from` attributes are used ). ### delete @@ -1809,7 +1810,7 @@ R: example_edit_backup_rotate.cf-before-edit.1 R: example_edit_backup_rotate.cf-before-edit.2 ``` -**See also:** [`default_repository` in ```body agent control```][cf-agent#default_repository], [`copy_backup` in ```body copy_from```][files#copy_backup], [`rotate` in `body edit_defaults`][files#rotate] +**See also:** [`default_repository` in `body agent control`][cf-agent#default_repository], [`copy_backup` in `body copy_from`][files#copy_backup], [`rotate` in `body edit_defaults`][files#rotate] #### empty_file_before_editing @@ -1825,7 +1826,7 @@ recipe allows an ordered procedure to be convergent. **Notes:** -* Within `edit_line` bundles the variable `$(edit.empty_before_use)` holds this value, allowing for decisions to be bade based on it. +- Within `edit_line` bundles the variable `$(edit.empty_before_use)` holds this value, allowing for decisions to be bade based on it. **Example:** @@ -1966,7 +1967,7 @@ rotate => "4"; } ``` -**See also:** [`edit_backup` in ```body edit_defaults```][files#edit_backup] +**See also:** [`edit_backup` in `body edit_defaults`][files#edit_backup] ### edit_line @@ -2003,7 +2004,7 @@ bundle agent example } ``` -**History:** Was introduced in 3.3.0, Nova 2.2.0 (2012). Mustache templates were introduced in 3.6.0. +**History:** Was introduced in 3.3.0, Nova 2.2.0 (2012). Mustache templates were introduced in 3.6.0. **See also:** [template_method][files#template_method], `template_data`, `readjson()`, `parsejson()`, `readyaml()`, `parseyaml()`, `mergedata()`, @@ -2517,7 +2518,7 @@ Note that symlink is synonymous with absolute links, which are different from relative links. Although all of these are symbolic links, the nomenclature here is defined such that symlink and absolute are equivalent . When verifying a link, choosing 'relative' means that the -link *must* be relative to the source, so relative and absolute links +link _must_ be relative to the source, so relative and absolute links are mutually exclusive. **Type:** (menu option) @@ -2536,6 +2537,7 @@ absolute **Example impelementation:** {{< CFEngine_include_snippet(masterfiles/lib/files.cf, ^body\slink_from\sln_s.*, ^##) >}} + ```cf3 body link_from example { @@ -2745,7 +2747,8 @@ File system attributes are not supported on all file systems and platforms. Hence, CFEngine will do it on a best effort basis (without any guarantees). **History:** -* Added in CFEngine 3.27.0 + +- Added in CFEngine 3.27.0 #### immutable @@ -2769,12 +2772,12 @@ that support it. CFEngine will simply ignore the immutable constraint if it's not supported and instead log a verbose message (to avoid too much noise). - If the immutable constraint is set to `"true"` and the promised file: - - **is not** immutable; then the agent will perform all other actions promised - before setting the immutable bit. - - **is** immutable; then the agent will temporarily clear the immutable bit. - The agent will do its best to keep the period of the temporarily cleared bit - as short as possible. The immutable bit may be temporarily cleared multiple - times during a files promise. + - **is not** immutable; then the agent will perform all other actions promised + before setting the immutable bit. + - **is** immutable; then the agent will temporarily clear the immutable bit. + The agent will do its best to keep the period of the temporarily cleared bit + as short as possible. The immutable bit may be temporarily cleared multiple + times during a files promise. - If the immutable constraint set to `"false"` and the promised file **is** immutable; then the immutable bit is cleared before performing any other actions promised. @@ -2783,7 +2786,7 @@ not supported and instead log a verbose message (to avoid too much noise). **History:** -* Added in CFEngine 3.27.0 +- Added in CFEngine 3.27.0 ### perms @@ -2917,8 +2920,8 @@ This is ignored on Windows, as the permission model uses ACLs. **History:** -* Default value changed from `true` to `false` in CFEngine 3.20.0 -* Added warning if default value is not explicitly set in 3.18.2, 3.20.0 +- Default value changed from `true` to `false` in CFEngine 3.20.0 +- Added warning if default value is not explicitly set in 3.18.2, 3.20.0 ### rename @@ -3131,7 +3134,7 @@ promise, unless the promises are grouped into a block using: ``` Variables, scalars and list variables are expanded within each promise -based on the current scope of the calling promise. If lines are +based on the current scope of the calling promise. If lines are grouped into a block, the whole block is repeated when lists are expanded (see the Special Topics Guide on editing). @@ -3208,8 +3211,8 @@ VirtualHost $(sys.ipv4[$(bundle.interfaces)]):443> #### template_method inline_mustache When [template_method][files#template_method] is `inline_mustache` the mustache input is not a file -but a string and you must set `edit_template_string`. The same rules apply -for `inline_mustache` and `mustache`. For mustache explanation see +but a string and you must set `edit_template_string`. The same rules apply +for `inline_mustache` and `mustache`. For mustache explanation see `template_method mustache` **Example:** @@ -3247,14 +3250,14 @@ currently supported. ##### template_method mustache Variables -The most basic tag type is the variable. A ```{{name}}``` tag in a basic +The most basic tag type is the variable. A `{{name}}` tag in a basic template will try to find the name key in the current context. If there is no name key, the parent contexts will be checked recursively. If the top context is reached and the name key is still not found, nothing will be rendered. **All variables are HTML escaped by default**. If you want to return unescaped -HTML, use the triple mustache: ```{{{name}}}``` or an ampersand -(```{{& name}}```). +HTML, use the triple mustache: `{{{name}}}` or an ampersand +(`{{& name}}`). A variable "miss" returns an empty string. @@ -3265,8 +3268,8 @@ A variable "miss" returns an empty string. Sections render blocks of text one or more times, depending on the value of the key in the current context. -A section begins with a pound and ends with a slash. That is, ```{{#key}}``` -begins a "person" section while ```{{/key}}``` ends it. +A section begins with a pound and ends with a slash. That is, `{{#key}}` +begins a "person" section while `{{/key}}` ends it. The behavior of the section is determined by the value of the key. @@ -3291,8 +3294,8 @@ single rendering of the block. ##### template_method mustache Inverted Sections An inverted section begins with a caret (hat) and ends with a slash. That is -```{{^key}}``` begins a "key" inverted section while -```{{/key}}``` ends it. +`{{^key}}` begins a "key" inverted section while +`{{/key}}` ends it. While sections can be used to render text one or more times based on the value of the key, inverted sections may render text once based on the inverse value of @@ -3310,7 +3313,7 @@ Comments begin with a bang and are ignored. Comments may contain newlines. ##### template_method mustache Set Delimiter Set Delimiter tags start with an equal sign and change the tag delimiters from -```{{``` and ```}}``` to custom strings. +`{{` and `}}` to custom strings. {{< CFEngine_include_example(mustache_set_delimiters.cf) >}} @@ -3330,7 +3333,7 @@ representation. Like output from `storejson()`. {{< CFEngine_include_example(mustache_extension_multiline_json.cf) >}} `$` variable prefix causing data to be rendered as compact json representation. -Like output from `format()` with the ```%S``` format string. +Like output from `format()` with the `%S` format string. {{< CFEngine_include_example(mustache_extension_compact_json.cf) >}} @@ -3367,11 +3370,11 @@ something else. **Notes:** -* The promised file *must* exist or the transformer will not be triggered. +- The promised file _must_ exist or the transformer will not be triggered. -* The transformer *should* result in the promised file no longer existing. +- The transformer _should_ result in the promised file no longer existing. -* By default, if the transformer returns zero, the promise will be considered +- By default, if the transformer returns zero, the promise will be considered repaired, even if the transformation does not result in the promised file becoming absent. Depending on other context restrictions this may result in the transformer being executed during each agent execution. For example: @@ -3380,14 +3383,14 @@ something else. transformer => "/bin/echo I found a file named $(this.promiser)", ``` -* The interpretation of the transformer return code can be managed similarly to +- The interpretation of the transformer return code can be managed similarly to `commands` type promises by using a `classes` body with `kept_returncodes`, `repaired_returncodes` and `failed_returncodes` attributes. -* `stdout` and `stderr` are redirected by CFEngine, and will not appear in any +- `stdout` and `stderr` are redirected by CFEngine, and will not appear in any output unless you run `cf-agent` with verbose logging. -* The command is not run in a shell. This means that you cannot perform file +- The command is not run in a shell. This means that you cannot perform file redirection or create pipelines. **Type:** `string` diff --git a/content/reference/promise-types/files/edit_line/_index.markdown b/content/reference/promise-types/files/edit_line/_index.markdown index d1f640d6c..b783c2d34 100644 --- a/content/reference/promise-types/files/edit_line/_index.markdown +++ b/content/reference/promise-types/files/edit_line/_index.markdown @@ -77,53 +77,54 @@ body location first_line There are several things to notice: -- The line-editing promises are all convergent promises about patterns - within the file. They have bodies, just like other attributes do and - these allow us to make simple templates about file editing while - extending the power of the basic primitives. -- All file edits specified in a single `edit_line` bundle are handled - "atomically". CFEngine edits files like this: - - CFEngine makes a copy of the file you you want to edit. - - CFEngine makes all the edits in the **copy** of the file. The - filename is the same as your original file with the extension - `.cf-after-edit` appended. - - After all promises are complete (the `vars`, `classes`, `delete_lines`, `field_edits`, - `insert_lines`, `replace_patterns`, and finally `reports` promises), - CFEngine checks to see if the new file is the same as the - original one. If there are no differences, the promises have - converged, so it deletes the copy, and the original is left - completely unmodified. - - If there are any differences, CFEngine makes a copy of your - original file with the extension `.cf-before-edit` (so you always - have the most recent backup available), and then renames the - edited version to your original filename. - - Because file rename is an atomic operation (guaranteed by the - operating system), any application program will either see the old - version of the file or the new one. There is no "window of - opportunity" where a partially edited file can be seen (unless an - application intentionally looks for the `.cf-after-edit` file). - Problems during editing (such as disk-full or permission errors) are - likewise detected, and CFEngine will not rename a partial file over - your original. -- All pattern matching is through Perl Compatible Regular Expressions -- Editing takes place within a marked region (which defaults to the - whole file if not otherwise specified). -- Search/replace functions now allow back-references. -- The line edit model now contains a field or column model for dealing - with tabular files such as Unix passwd and group files. We can now - apply powerful convergent editing operations to single fields inside - a table, to append, order and delete items from lists inside fields. -- The special variable `$(edit.filename)` contains the name of the - file being edited within an edit bundle. -- The special variable `$(edit.empty_before_use)` holds the current value of - `empty_file_before_editing` which can be set by `edit_defaults bodies`. This - is used to know if the prior state of the file will have any effect on the - promise. -- On Windows, a text file may be stored stored either with CRLF line - endings (Windows style), or LF line endings (Unix style). CFEngine - will respect the existing line ending type and make modifications - using the same type. New files will get CRLF line ending type. +- The line-editing promises are all convergent promises about patterns + within the file. They have bodies, just like other attributes do and + these allow us to make simple templates about file editing while + extending the power of the basic primitives. +- All file edits specified in a single `edit_line` bundle are handled + "atomically". CFEngine edits files like this: + - CFEngine makes a copy of the file you you want to edit. + - CFEngine makes all the edits in the **copy** of the file. The + filename is the same as your original file with the extension + `.cf-after-edit` appended. + - After all promises are complete (the `vars`, `classes`, `delete_lines`, `field_edits`, + `insert_lines`, `replace_patterns`, and finally `reports` promises), + CFEngine checks to see if the new file is the same as the + original one. If there are no differences, the promises have + converged, so it deletes the copy, and the original is left + completely unmodified. + - If there are any differences, CFEngine makes a copy of your + original file with the extension `.cf-before-edit` (so you always + have the most recent backup available), and then renames the + edited version to your original filename. + + Because file rename is an atomic operation (guaranteed by the + operating system), any application program will either see the old + version of the file or the new one. There is no "window of + opportunity" where a partially edited file can be seen (unless an + application intentionally looks for the `.cf-after-edit` file). + Problems during editing (such as disk-full or permission errors) are + likewise detected, and CFEngine will not rename a partial file over + your original. + +- All pattern matching is through Perl Compatible Regular Expressions +- Editing takes place within a marked region (which defaults to the + whole file if not otherwise specified). +- Search/replace functions now allow back-references. +- The line edit model now contains a field or column model for dealing + with tabular files such as Unix passwd and group files. We can now + apply powerful convergent editing operations to single fields inside + a table, to append, order and delete items from lists inside fields. +- The special variable `$(edit.filename)` contains the name of the + file being edited within an edit bundle. +- The special variable `$(edit.empty_before_use)` holds the current value of + `empty_file_before_editing` which can be set by `edit_defaults bodies`. This + is used to know if the prior state of the file will have any effect on the + promise. +- On Windows, a text file may be stored stored either with CRLF line + endings (Windows style), or LF line endings (Unix style). CFEngine + will respect the existing line ending type and make modifications + using the same type. New files will get CRLF line ending type. In the example above, back references are used to allow conversion of comments from shell-style to C-style. @@ -168,8 +169,8 @@ bundles. **Type:** `body select_region` -Restrict edits to a specific region of a file based on ```select_start``` -and ```select_end``` regular expressions. If the beginning and ending regular +Restrict edits to a specific region of a file based on `select_start` +and `select_end` regular expressions. If the beginning and ending regular expressions match more than one region only the first region will be selected for editing. @@ -292,9 +293,9 @@ The solution to this problem is simple: if the marker for a region needs to be r In the example above it is enough to change the markers from "BEGIN" to "header" and from "END" to "trailer" to obtain the desired result. -**** +--- -#### include\_end\_delimiter +#### include_end_delimiter **Description:** Whether to include the section delimiter @@ -332,7 +333,7 @@ Input file: The section does not normally include the line containing }. By setting `include_end_delimiter` to `true` it would be possible for example, to delete the entire section, including the section trailer. If however -`include_end_delimiter` is false, the *contents* of the section could be +`include_end_delimiter` is false, the _contents_ of the section could be deleted, but the header would be unaffected by any `delete_lines` promises. @@ -346,7 +347,7 @@ in `include_start_delimiter`). - Introduced in CFEngine version 3.0.5 (2010) -#### include\_start\_delimiter +#### include_start_delimiter **Description:** Whether to include the section delimiter @@ -383,7 +384,7 @@ In this example, the section does not normally include the line [My section]. By setting `include_start_delimiter` to `true` it would be possible for example, to delete the entire section, including the section header. If however `include_start_delimiter` is false, the -*contents* of the section could be deleted, but the header would be +_contents_ of the section could be deleted, but the header would be unaffected by any `delete_lines` promises. See the next section on `include_start_delimiter` for further details. @@ -391,9 +392,9 @@ unaffected by any `delete_lines` promises. See the next section on - Introduced in CFEngine version 3.0.5 (2010) -#### select\_end +#### select_end -**Description:** [Anchored][anchored] regular expression matches end of edit region from ```select_start``` +**Description:** [Anchored][anchored] regular expression matches end of edit region from `select_start` **Type:** `string` @@ -415,11 +416,11 @@ then just omit the `select_end` promise and the selected region will run to the end of the file. **Note:** When a region does not always have an end (like the last section of an -INI formatted file) ```select_end_match_eof``` can be used to allow the end of +INI formatted file) `select_end_match_eof` can be used to allow the end of the file to be considered the end of the region. The global default can be modified with [`select_end_match_eof`][cf-agent#select_end_match_eof]. -#### select\_end\_match\_eof +#### select_end_match_eof **Description:** Allow the end of a file to be considered the end of a region. @@ -449,7 +450,7 @@ select_end_match_eof => "true"; - Introduced in CFEngine version 3.9.0 (2016) -#### select\_start +#### select_start **Description:** [Anchored][anchored] regular expression matching start of edit region diff --git a/content/reference/promise-types/files/edit_line/delete_lines.markdown b/content/reference/promise-types/files/edit_line/delete_lines.markdown index c505e3d3d..aa7d09032 100644 --- a/content/reference/promise-types/files/edit_line/delete_lines.markdown +++ b/content/reference/promise-types/files/edit_line/delete_lines.markdown @@ -24,17 +24,17 @@ Note that typically, only a single line is specified in each promises that each delete a line. It is also possible to specify multi-line `delete_lines` promises. -However, these promises will only delete those lines if *all* the lines -are present in the file *in exactly the same order* as specified in the +However, these promises will only delete those lines if _all_ the lines +are present in the file _in exactly the same order_ as specified in the promise (with no intervening lines). That is, all the lines must match as a unit for the `delete_lines` promise to be kept. If the promiser contains multiple lines, then CFEngine assumes that all of the lines must exist as a contiguous block in order to be deletes. -This gives preserve\_block semantics to any multiline `delete_lines` +This gives preserve_block semantics to any multiline `delete_lines` promise. -*** +--- ## Attributes @@ -113,7 +113,7 @@ delete_if_not_startwith_from_list => { @(s) }; #### delete_if_match_from_list -**Description:** Delete lines from a file if the lines *completely* match any of the [anchored][anchored] regular expressions listed. +**Description:** Delete lines from a file if the lines _completely_ match any of the [anchored][anchored] regular expressions listed. Note that this attribute modifies the selection criteria, it does not make the initial selection, and the match determination is made only on promised lines. @@ -133,7 +133,7 @@ delete_if_match_from_list => { @(s) }; #### delete_if_not_match_from_list -**Description:** Delete lines from a file unless the lines *completely* match any of the [anchored][anchored] regular expressions listed. +**Description:** Delete lines from a file unless the lines _completely_ match any of the [anchored][anchored] regular expressions listed. Note that this attribute modifies the selection criteria, it does not make the initial selection, and the match determination is made only on promised lines. @@ -222,4 +222,4 @@ delete_lines: This body applies to all promise types within `edit_line` bundles. -**See also:** [```select_region``` with `edit_line` operations][edit_line#select_region], [```select_region``` in `field_edits`][field_edits#select_region], [```select_region``` in `insert_lines`][field_edits#select_region], [```select_region``` in `replace_patterns`][replace_patterns#select_region] +**See also:** [`select_region` with `edit_line` operations][edit_line#select_region], [`select_region` in `field_edits`][field_edits#select_region], [`select_region` in `insert_lines`][field_edits#select_region], [`select_region` in `replace_patterns`][replace_patterns#select_region] diff --git a/content/reference/promise-types/files/edit_line/field_edits.markdown b/content/reference/promise-types/files/edit_line/field_edits.markdown index 8ccf4f20e..9c4317dc6 100644 --- a/content/reference/promise-types/files/edit_line/field_edits.markdown +++ b/content/reference/promise-types/files/edit_line/field_edits.markdown @@ -5,7 +5,7 @@ title: field_edits Certain types of text files are tabular in nature, with field separators (e.g. `:` or `,`). The `passwd` and group files are classic examples of tabular -files, but there are many ways to use this feature. For example, editing a +files, but there are many ways to use this feature. For example, editing a string: ```cf3 @@ -89,7 +89,7 @@ Then a `field_edits` body describes the separators for fields and one level of sub-fields, along with policies for editing these fields, ordering the items within them. -*** +--- ## Attributes @@ -145,7 +145,7 @@ triggering an error. If a user specifies a field that does not exist, because there are not so many fields, this allows the number of fields to be extended. Without this setting, CFEngine will issue an error if a non-existent field is referenced. Blank -fields in a tabular file can be eliminated or kept depending in this setting. +fields in a tabular file can be eliminated or kept depending in this setting. If in doubt, set this to true. **Type:** [`boolean`][boolean] @@ -172,26 +172,26 @@ files. **Allowed input range:** -* `append` +- `append` Append the specified value to the end of the field/column, separating (potentially) multiple values with `value_separator` -* `prepend` +- `prepend` Prepend the specified value at the beginning of the field/column, separating (potentially) multiple values with `value_separator` -* `alphanum` +- `alphanum` Insert the specified value into the field/column, keeping all the values (separated by `value_separator`) in alphanumerically sorted order -* `set` +- `set` Replace the entire field/column with the specified value. -* `delete` +- `delete` Delete the specified value (if present) in the specified field/column. @@ -307,4 +307,4 @@ value_separator => ","; This body applies to all promise types within `edit_line` bundles. -**See also:** [```select_region``` with `edit_line` operations][edit_line#select_region], [```select_region``` in `delete_lines`][delete_lines#select_region], [```select_region``` in `insert_lines`][insert_lines#select_region], [```select_region``` in `replace_patterns`][replace_patterns#select_region] +**See also:** [`select_region` with `edit_line` operations][edit_line#select_region], [`select_region` in `delete_lines`][delete_lines#select_region], [`select_region` in `insert_lines`][insert_lines#select_region], [`select_region` in `replace_patterns`][replace_patterns#select_region] diff --git a/content/reference/promise-types/files/edit_line/insert_lines.markdown b/content/reference/promise-types/files/edit_line/insert_lines.markdown index af0810dc9..0998733da 100644 --- a/content/reference/promise-types/files/edit_line/insert_lines.markdown +++ b/content/reference/promise-types/files/edit_line/insert_lines.markdown @@ -70,7 +70,7 @@ line two" } ``` -**** +--- ## Attributes @@ -127,15 +127,15 @@ lines. **Allowed input range:** -* `literal` or `string` +- `literal` or `string` Treat the promiser as a literal string of convergent lines. -* file +- file The string should be interpreted as a filename from which to import lines. -* `preserve_block` +- `preserve_block` The default behavior assumes that multi-line entries are not ordered specifically. They should be treated as a collection of lines of text, @@ -148,7 +148,7 @@ already exist, they will be added again as a coherent block. Thus if you suspect that some stray / conflicting lines might be present they should be cleaned up with `delete_lines` first. -* `preserve_all_lines` +- `preserve_all_lines` Disables idempotency during the insertion of a block of text so that multiple identical lines may be inserted. @@ -157,7 +157,7 @@ This means that the text will be inserted to the file even if it is already present. To avoid that the file grows, use this together with `empty_file_before_editing`. -* `file_preserve_block` +- `file_preserve_block` Interpret the string as a filename, and assume `preserve_block` semantics. This was added in CFEngine 3.5.x. @@ -235,7 +235,7 @@ insert_if_startwith_from_list => { "find_me_1", "find_me_2" }; **Description:** Insert line if it DOES NOT start with a string in the list The complement of `insert_if_startwith_from_list`. If the start of a -line does *not* match one of the strings, that line is inserted into the +line does _not_ match one of the strings, that line is inserted into the file being edited. `insert_if_not_startswith_from_list` is ignored unless `insert_type` is @@ -260,7 +260,7 @@ insert_if_not_startwith_from_list => { "find_me_1", "find_me_2" }; The list contains literal strings to search for in the secondary file (the file being read via the `insert_type` attribute, not the main file -being edited). If the regex matches a *complete* line of the file, that +being edited). If the regex matches a _complete_ line of the file, that line from the secondary file will be inserted at the present location in the primary file. That is, the regex's in the list are [anchored][anchored]. @@ -284,7 +284,7 @@ insert_if_match_from_list => { ".*find_.*_1.*", ".*find_.*_2.*" }; **Description:** Insert line if it DOES NOT fully match a regex in the list -The complement of `insert_if_match_from_list`. If the line does *not* +The complement of `insert_if_match_from_list`. If the line does _not_ match a line in the secondary file, it is inserted into the file being edited. @@ -335,7 +335,7 @@ insert_if_contains_from_list => { "find_me_1", "find_me_2" }; **Description:** Insert line if a regex in the list DOES NOT match a line fragment. -The complement of `insert_if_contains_from_list`. If the line is *not* +The complement of `insert_if_contains_from_list`. If the line is _not_ found in the secondary file, it is inserted into the file being edited. `insert_if_not_contains_from_list` is ignored unless `insert_type` is @@ -447,8 +447,8 @@ select_line_matching => "Expression match.* whole line"; **Notes:** -* This attribute is mutually exclusive of `select_line_number`. -* This attribute can not match a multiple line pattern (`(?m)` has no effect). +- This attribute is mutually exclusive of `select_line_number`. +- This attribute can not match a multiple line pattern (`(?m)` has no effect). ### select_region @@ -456,7 +456,7 @@ select_line_matching => "Expression match.* whole line"; This body applies to all promise types within `edit_line` bundles. -**See also:** [```select_region``` with `edit_line` operations][edit_line#select_region], [```select_region``` in `delete_lines`][delete_lines#select_region], [```select_region``` in `field_edits`][field_edits#select_region], [```select_region``` in `replace_patterns`][replace_patterns#select_region] +**See also:** [`select_region` with `edit_line` operations][edit_line#select_region], [`select_region` in `delete_lines`][delete_lines#select_region], [`select_region` in `field_edits`][field_edits#select_region], [`select_region` in `replace_patterns`][replace_patterns#select_region] ### whitespace_policy @@ -464,7 +464,7 @@ This body applies to all promise types within `edit_line` bundles. The white space matching policy applies only to `insert_lines`, as a convenience. It works by rewriting the insert string as a regular -expression when *matching* lines (that is, when determining if the line +expression when _matching_ lines (that is, when determining if the line is already in the file), but leaving the string as specified when actually inserting it. diff --git a/content/reference/promise-types/files/edit_line/replace_patterns.markdown b/content/reference/promise-types/files/edit_line/replace_patterns.markdown index 9f5317098..e470dd834 100644 --- a/content/reference/promise-types/files/edit_line/replace_patterns.markdown +++ b/content/reference/promise-types/files/edit_line/replace_patterns.markdown @@ -39,7 +39,7 @@ the remainder of the line will not be affected. You can also use PCRE look-behind and look-ahead patterns to restrict the lines upon which the pattern will match. -**** +--- ## Attributes @@ -62,11 +62,11 @@ applies to. **Allowed input range:** -* `all` +- `all` Replace all occurrence. -* `first` +- `first` Replace only the first occurrence. Note: this is non-convergent. @@ -104,4 +104,4 @@ replace_value => "$(s)"; This body applies to all promise types within `edit_line` bundles. -**See also:** [```select_region``` with `edit_line` operations][edit_line#select_region], [```select_region``` in `delete_lines`][delete_lines#select_region], [```select_region``` in `field_edits`][field_edits#select_region], [```select_region``` in `insert_lines`][insert_lines#select_region] +**See also:** [`select_region` with `edit_line` operations][edit_line#select_region], [`select_region` in `delete_lines`][delete_lines#select_region], [`select_region` in `field_edits`][field_edits#select_region], [`select_region` in `insert_lines`][insert_lines#select_region] diff --git a/content/reference/promise-types/files/edit_xml/_index.markdown b/content/reference/promise-types/files/edit_xml/_index.markdown index adcec3770..ef6cce693 100644 --- a/content/reference/promise-types/files/edit_xml/_index.markdown +++ b/content/reference/promise-types/files/edit_xml/_index.markdown @@ -14,13 +14,14 @@ the `files` promise needs to be the XML document that is being edited. Within an `edit_xml` bundle, various promise types are available to create new or manipulate existing XML documents. -*** +--- ## Common attributes + diff --git a/content/reference/promise-types/guest_environments.markdown b/content/reference/promise-types/guest_environments.markdown index 107597279..84894dade 100644 --- a/content/reference/promise-types/guest_environments.markdown +++ b/content/reference/promise-types/guest_environments.markdown @@ -18,10 +18,10 @@ with interfaces to an external environment. CFEngine currently seeks to add convergence properties to existing interfaces for automatic self-healing of guest environments. The current -implementation integrates with *libvirt*, supporting host virtualization +implementation integrates with _libvirt_, supporting host virtualization for Xen, KVM, VMWare, etc. Thus CFEngine, running on a virtual host, can maintain the state and deployment of virtual guest machines defined -within the *libvirt* framework. Guest environment promises are not meant +within the _libvirt_ framework. Guest environment promises are not meant to manage what goes on within the virtual guests. For that purpose you should run CFEngine directly on the virtual machine, as if it were any other machine. @@ -44,9 +44,9 @@ site1:: environment_host => "atlas"; ``` -CFEngine currently provides a convergent interface to *libvirt*. +CFEngine currently provides a convergent interface to _libvirt_. -*** +--- ## Attributes @@ -332,30 +332,30 @@ This attribute conflicts with `env_cpus`, `env_memory` and `env_disk`. ### environment_state **Description:** The `environment_state` defines the desired dynamic state - of the specified environment. +of the specified environment. **Type:** (menu option) **Allowed input range:** -* `create` +- `create` The guest machine is allocated, installed and left in a running state. -* `delete` +- `delete` The guest machine is shut down and deallocated, but no files are removed. -* `running` +- `running` The guest machine is in a running state, if it previously exists. -* `suspended` +- `suspended` The guest exists in a suspended state or a shutdown state. If the guest is running, it is suspended; otherwise it is ignored. -* `down` +- `down` The guest machine is shut down, but not deallocated. @@ -378,7 +378,7 @@ guest_environments: **Description:** `environment_type` defines the virtual environment type. -The currently supported types are those supported by *libvirt*. More +The currently supported types are those supported by _libvirt_. More will be added in the future. **Type:** (menu option) diff --git a/content/reference/promise-types/measurements.markdown b/content/reference/promise-types/measurements.markdown index fce3f4823..f0ce5bcd4 100644 --- a/content/reference/promise-types/measurements.markdown +++ b/content/reference/promise-types/measurements.markdown @@ -81,7 +81,7 @@ what to do with the result afterwards. **History:** -* Custom measurements open sourced in 3.12.0 +- Custom measurements open sourced in 3.12.0 ## Architecture @@ -101,7 +101,7 @@ cf-check dump /var/cfengine/state/cf_observations.lmdb By default in the [Masterfiles Policy Framework][Masterfiles Policy Framework], `cf-serverd` uses two variables, `def.default_data_select_host_monitoring_include` and `def.default_data_select_policy_hub_monitoring_include` to [configure which measurements will be included in enterprise reporting][mpf-configure-measurement-collection]. -On the hub side, reports are collected and measurements data is inserted into the [`MonitoringHG`][cfdb#Table: MonitoringYrMeta] [`MonitoringMgMeta`][cfdb#Table: MonitoringMgMeta] and [`MonitoringYrMeta`][cfdb#Table: MonitoringYrMeta] tables of the Enterprise Hub database. +On the hub side, reports are collected and measurements data is inserted into the [`MonitoringHG`][cfdb#Table: MonitoringYrMeta] [`MonitoringMgMeta`][cfdb#Table: MonitoringMgMeta] and [`MonitoringYrMeta`][cfdb#Table: MonitoringYrMeta] tables of the Enterprise Hub database. A diagnostic query to run with a [Custom Report in Mission Portal][Reporting UI]. @@ -119,7 +119,7 @@ data or not. SELECT * FROM monitoringmgmeta; ``` -Measurement data is presented in Mission Portal in the [`Measurements App`][Measurements App] and in the ```Measurements``` section of the [`Host info page`][Hosts#Host info]. +Measurement data is presented in Mission Portal in the [`Measurements App`][Measurements App] and in the `Measurements` section of the [`Host info page`][Hosts#Host info]. When policy is changed in regards to monitor bundles, both `cf-monitord` _and_ `cf-serverd` should be restarted in order to receive the updated policy. @@ -146,7 +146,7 @@ variable to which data will be reported. Log files are created under context called `mon`, analogous to the system variables in sys. Thus the values may be used in other promises in the form `$(mon.handle)`. -*** +--- ## Attributes @@ -154,7 +154,7 @@ may be used in other promises in the form `$(mon.handle)`. **Description:** The datatype being collected. -**Default:** ```pipe``` +**Default:** `pipe` CFEngine treats all input using a stream abstraction. The preferred interface is files, since they can be read without incurring the cost of a process. @@ -218,22 +218,22 @@ isolated value **Allowed input range:** -* `scalar` +- `scalar` A single value, with compressed statistics is retained. The value of the data is not expected to change much for the lifetime of the daemon (and so will be sampled less often by cf-monitord). -* `static` +- `static` A synonym for 'scalar'. -* `log` +- `log` The measured value is logged as an infinite time-series in `$(sys.workdir)/state/_measure.log`. -* `weekly` +- `weekly` A standard CFEngine two-dimensional time average (over a weekly period) is retained. @@ -253,10 +253,10 @@ is retained. **Notes:** -* Measurements with history type `weekly` _are collected_ by CFEngine Enterprise reporting. -* Measurements with history type `static` are _not collected_ by CFEngine Enterprise reporting. -* Measurements with history type `scalar` are _not collected_ by CFEngine Enterprise reporting. -* Measurements with history type `log` are _not collected_ by CFEngine Enterprise reporting. +- Measurements with history type `weekly` _are collected_ by CFEngine Enterprise reporting. +- Measurements with history type `static` are _not collected_ by CFEngine Enterprise reporting. +- Measurements with history type `scalar` are _not collected_ by CFEngine Enterprise reporting. +- Measurements with history type `log` are _not collected_ by CFEngine Enterprise reporting. ### units diff --git a/content/reference/promise-types/methods.markdown b/content/reference/promise-types/methods.markdown index 6f68bee6a..c7fbbc11d 100644 --- a/content/reference/promise-types/methods.markdown +++ b/content/reference/promise-types/methods.markdown @@ -92,7 +92,7 @@ methods: ``` Please note that method names must be either simple strings or slists. -They can't be array references, for instance. As a rule, they can +They can't be array references, for instance. As a rule, they can only look like `$(name)` where `name` is either a string or an slist. They can't be `"$(a)$(b)"`, `$(a[b])`, and so on. @@ -110,7 +110,7 @@ Output: 2013-12-11T13:33:31-0500 notice: /run/methods/'call'/unpack/methods/'relay'/call_2: R: call_2: called with parameters p and q ``` -*** +--- ## Attributes diff --git a/content/reference/promise-types/packages-deprecated.markdown b/content/reference/promise-types/packages-deprecated.markdown index f5cbd4a1d..20b5c07b6 100644 --- a/content/reference/promise-types/packages-deprecated.markdown +++ b/content/reference/promise-types/packages-deprecated.markdown @@ -16,7 +16,7 @@ packages. The bundles can be found in the file packages.cf in masterfiles. CFEngine supports a generic approach to integration with native operating support for packaging. Package promises allow CFEngine to make -promises regarding the state of software packages *conditionally*, given +promises regarding the state of software packages _conditionally_, given the assumption that a native package manager will perform the actual manipulations. Since no agent can make unconditional promises about another, this is the best that can be achieved. @@ -40,20 +40,20 @@ packages: Packages are treated as black-boxes with three labels: -- A package name -- A version string -- An architecture name +- A package name +- A version string +- An architecture name Package managers are treated as black boxes that may support some or all of the following promise types: -- List installed packages -- Add packages -- Delete packages -- Reinstall (repair) packages -- Update packages -- Patch packages -- Verify packages +- List installed packages +- Add packages +- Delete packages +- Reinstall (repair) packages +- Update packages +- Patch packages +- Verify packages If these services are promised by a package manager, `cf-agent` promises to use the service and encapsulate it within the overall CFEngine @@ -79,11 +79,11 @@ good faith. Packages are basically 'outsourced', to invoke IT parlance. ### Behavior A package promise consists of a name, a version and an architecture, -*(n,v,a)*, and behavior to be promised about packages that match -criteria based on these. The components *(n,v,a)* can be determined in +_(n,v,a)_, and behavior to be promised about packages that match +criteria based on these. The components _(n,v,a)_ can be determined in one of two different ways: -* They may be specified independently, e.g. +- They may be specified independently, e.g. ```cf3 packages: @@ -97,10 +97,10 @@ packages: package_version => "1.2.3"; ``` -* They may be extracted from a package identifier (promiser) or - filename, using pattern matching. For example, a promiser - 7-Zip-4.50-x86_64.msi and a `package_method` containing the - following: +- They may be extracted from a package identifier (promiser) or + filename, using pattern matching. For example, a promiser + 7-Zip-4.50-x86_64.msi and a `package_method` containing the + following: ```cf3 package_name_regex => "^(\S+)-(\d+\.?)+"; @@ -109,7 +109,7 @@ package_arch_regex => "^\S+-[\d\.]+-(.*).msi"; ``` When scanning a list of installed packages different managers present -the information *(n,v,a)* in quite different forms and pattern +the information _(n,v,a)_ in quite different forms and pattern extraction is necessary. When making a promise about a specific package, the CFEngine user may choose one or the other model. @@ -134,23 +134,23 @@ Normal ordering for packages is the following: **Identified package matched by name, but not version** -| Command | Dumb manager | Smart manager | -|---------|--------------|---------------| -| add | unable | Never | -| delete | unable | Attempt deletion | -| reinstall | unable | Attempt delete/add | -| upgrade | unable | Upgrade if capable | -| patch | unable | Patch if capable | +| Command | Dumb manager | Smart manager | +| --------- | ------------ | ------------------ | +| add | unable | Never | +| delete | unable | Attempt deletion | +| reinstall | unable | Attempt delete/add | +| upgrade | unable | Upgrade if capable | +| patch | unable | Patch if capable | **Package not installed** -| Command | Dumb manager | Smart manager | -|---------|--------------|---------------| -| add | Attempt to install named | Install any version | -| delete | unable | unable | -| reinstall | Attempt to install named | unable | -| upgrade | unable | unable | -| patch | unable | unable | +| Command | Dumb manager | Smart manager | +| --------- | ------------------------ | ------------------- | +| add | Attempt to install named | Install any version | +| delete | unable | unable | +| reinstall | Attempt to install named | unable | +| upgrade | unable | unable | +| patch | unable | unable | ```cf3 bundle agent packages @@ -205,9 +205,9 @@ without specific patch arguments. If so, that command can be called periodically under `commands`. The main purposes of patching body items are: -- To install specific named patches in a controlled manner. -- To generate reports of available and installed patches during system - reporting. +- To install specific named patches in a controlled manner. +- To generate reports of available and installed patches during system + reporting. ### Installers without package/patch arguments @@ -301,7 +301,7 @@ This is for use when extracting architecture from the name of the promiser, when the architecture is not specified using the `package_architectures` list. It is an [unanchored][unanchored] regular expression that contains exactly one parenthesized back-reference which marks the location in -the *promiser* at which the architecture is specified. +the _promiser_ at which the architecture is specified. **Type:** `string` @@ -668,7 +668,7 @@ package_name_convention => "$(name).$(arch).rpm"; **Description:** Regular expression with one back-reference to extract package name string -This [unanchored][unanchored] regular expression is only used when the *promiser* contains +This [unanchored][unanchored] regular expression is only used when the _promiser_ contains not only the name of the package, but its version and architecture also. In that case, this expression should contain a single parenthesized back-reference to extract the name of the package from the string. @@ -1083,37 +1083,37 @@ system **Allowed input range:** -* `add` +- `add` Ensure that a package is present (this is the default setting from 3.3.0). -* `delete` +- `delete` Ensure that a package is not present. -* `reinstall` +- `reinstall` Delete then add package (warning, non-convergent). -* `update` +- `update` Update the package if an update is available (manager dependent). -* `addupdate` +- `addupdate` Equivalent to add if the package is not installed, and update if it is installed. Note: This attribute requires the specification of `package_version` and `package_select` in order to select the proper version to update to if -available. *See also* [package_latest][lib/packages.cf#package_latest] +available. _See also_ [package_latest][lib/packages.cf#package_latest] [package_specific_latest][lib/packages.cf#package_specific_latest] in the standard library. -* `patch` +- `patch` Install one or more patches if available (manager dependent). -* `verify` +- `verify` Verify the correctness of the package (manager dependent). The promise is kept if the package is installed correctly, not kept otherwise. diff --git a/content/reference/promise-types/packages.markdown b/content/reference/promise-types/packages.markdown index 81e72d21b..bdc8f3c0a 100644 --- a/content/reference/promise-types/packages.markdown +++ b/content/reference/promise-types/packages.markdown @@ -43,7 +43,7 @@ string needs to be a bare package name, you cannot use a file name for this. **Noteable differences from `package_method` based implementation:** -* The promiser must be the fully qualified path to a file *or* a *package name*. +- The promiser must be the fully qualified path to a file _or_ a _package name_. `package_modules` do not have the concept of a flexible [naming convention][packages (deprecated)#package_name_convention]. @@ -148,7 +148,7 @@ packages: **Description:** Whether the package should be present or absent on the system. -**Default value:** ```present``` +**Default value:** `present` **Type:** `string` @@ -341,9 +341,10 @@ body package_module yum_all_repos **History:** Introduced in 3.13.0, 3.12.2 ## Package modules out-of-the-box + ### yum -Manage packages using ```yum```. This is the [default package module][lib/packages.cf#package_module_knowledge] for Red Hat, CentOS and Amazon Linux. +Manage packages using `yum`. This is the [default package module][lib/packages.cf#package_module_knowledge] for Red Hat, CentOS and Amazon Linux. **Examples:** @@ -394,11 +395,11 @@ bundle agent example **Notes:** -* Supports file path and repository sourced packages. +- Supports file path and repository sourced packages. -* Requires Python version 2 or 3 to be installed on the host. +- Requires Python version 2 or 3 to be installed on the host. -* If ```policy => "present"``` *and* ```version``` is set this package module will downgrade the promised package if necessary. +- If `policy => "present"` _and_ `version` is set this package module will downgrade the promised package if necessary. ```console [root ~]# yum --show-duplicates list screen @@ -437,12 +438,12 @@ bundle agent example **History:** -* Added in CFEngine 3.7.0 -* `enablerepo` and `disablerepo` option support added in 3.7.8, 3.10.4, 3.12.0 +- Added in CFEngine 3.7.0 +- `enablerepo` and `disablerepo` option support added in 3.7.8, 3.10.4, 3.12.0 ### apt_get -Manage packages using ```apt-get```. +Manage packages using `apt-get`. **Example:** @@ -468,14 +469,14 @@ packages: **Notes:** -* Requires Python version 2 to be installed on the host. -* Supports [```options```][packages#options] attribute. Each space separate +- Requires Python version 2 to be installed on the host. +- Supports [`options`][packages#options] attribute. Each space separate option must be added as a separate list element. The options are passed directly through to the package manager. **History:** -* Added in CFEngine 3.7.0 +- Added in CFEngine 3.7.0 ### freebsd_ports @@ -484,7 +485,7 @@ FreeBSD [Ports](https://www.freebsd.org/doc/handbook/ports-using.html). **History:** -* Added in CFEngine 3.9.0 +- Added in CFEngine 3.9.0 ### nimclient @@ -503,13 +504,13 @@ packages: **Notes:** -* [```options```][packages#options] attribute support to specify - ```lpp_source```. Please note it is **REQUIRED** to specify an - ```lpp_source``` when using this package module. +- [`options`][packages#options] attribute support to specify + `lpp_source`. Please note it is **REQUIRED** to specify an + `lpp_source` when using this package module. **History:** -* Added in CFEngine 3.9.0 +- Added in CFEngine 3.9.0 ### pkg @@ -539,15 +540,15 @@ packages: **Notes:** -* Supports [```options```][packages#options] attribute. - * `option` :: Allows specification of additional options ( `-o` ) - * `repository` :: Allows specification of repository ( `-r` ) +- Supports [`options`][packages#options] attribute. + - `option` :: Allows specification of additional options ( `-o` ) + - `repository` :: Allows specification of repository ( `-r` ) **History:** -* Added in CFEngine 3.9.0 -* Added `repo` alias for repository option in CFEngine 3.20.0, 3.18.2 -* Added `option` option in CFEngine 3.20.0, 3.18.2 +- Added in CFEngine 3.9.0 +- Added `repo` alias for repository option in CFEngine 3.20.0, 3.18.2 +- Added `option` option in CFEngine 3.20.0, 3.18.2 ### pkgsrc @@ -555,7 +556,7 @@ Manage packages using [pkgsrc](https://www.pkgsrc.org). **History:** -* Added in CFEngine 3.9.0 +- Added in CFEngine 3.9.0 ### slackpkg @@ -573,7 +574,7 @@ packages: **History:** -* Added in CFEngine 3.12.0 +- Added in CFEngine 3.12.0 ### msiexec @@ -605,7 +606,7 @@ packages: **History:** -* Added in CFEngine 3.12.2 and 3.14.0 +- Added in CFEngine 3.12.2 and 3.14.0 ### snap @@ -643,9 +644,9 @@ bundle agent main **History:** -* Added in CFEngine 3.15.0, 3.12.3, 3.10.7 +- Added in CFEngine 3.15.0, 3.12.3, 3.10.7 **Notes:** -- version `latest` is *not* supported when promising an absence -- `list-updates` is *not* implemented, snaps are automatically updated by default +- version `latest` is _not_ supported when promising an absence +- `list-updates` is _not_ implemented, snaps are automatically updated by default diff --git a/content/reference/promise-types/processes.markdown b/content/reference/promise-types/processes.markdown index 2e1d4caa7..4475377e0 100644 --- a/content/reference/promise-types/processes.markdown +++ b/content/reference/promise-types/processes.markdown @@ -78,15 +78,15 @@ commands: **Notes:** -* CFEngine will not allow you to signal processes 1-4 or the agent process +- CFEngine will not allow you to signal processes 1-4 or the agent process itself for fear of bringing down the system. -* Process promises depend on the `ps` native tool, which by default truncates +- Process promises depend on the `ps` native tool, which by default truncates lines at 128 columns on HP-UX. It is recommended to edit the file `/etc/default/ps` and increase the `DEFAULT_CMD_LINE_WIDTH` setting to 1024 to guarantee that process promises will work smoothly on that platform. -**** +--- ## Attributes @@ -585,4 +585,4 @@ processes: **History:** -* 3.18.2, 3.20.0 Added ability to sleep between signals using `Ns` +- 3.18.2, 3.20.0 Added ability to sleep between signals using `Ns` diff --git a/content/reference/promise-types/reports.markdown b/content/reference/promise-types/reports.markdown index 206c7143e..9d76ed404 100644 --- a/content/reference/promise-types/reports.markdown +++ b/content/reference/promise-types/reports.markdown @@ -30,7 +30,7 @@ bundle agent report ``` Reports do not fundamentaly make changes to the system and report type promise -outcomes are *always* considered kept. +outcomes are _always_ considered kept. ```cf3 bundle agent report @@ -67,7 +67,7 @@ R: found class: report_reached R: found class: report_not_repaired ``` -**** +--- ## Attributes diff --git a/content/reference/promise-types/roles.markdown b/content/reference/promise-types/roles.markdown index 1cb6acd61..c8ec639cd 100644 --- a/content/reference/promise-types/roles.markdown +++ b/content/reference/promise-types/roles.markdown @@ -33,7 +33,7 @@ In this example user `mark` is granted permission to remotely activate classes matching the regular expression `Myclass_.*` hen using the `cf-runagent` to activate CFEngine. -**** +--- ## Attributes diff --git a/content/reference/promise-types/services.markdown b/content/reference/promise-types/services.markdown index 71d76ea76..778d1367b 100644 --- a/content/reference/promise-types/services.markdown +++ b/content/reference/promise-types/services.markdown @@ -3,7 +3,7 @@ layout: default title: services --- -`services` type promises in their simplest *generic* form are an abstraction on +`services` type promises in their simplest _generic_ form are an abstraction on **bundles**. `services` type promises are implemented by mapping a bundle to `service_bundle` in a `service_method` body. Reference the [services bodies and bundles in the standard library][lib/services.cf]. @@ -130,7 +130,7 @@ for services promises. **History:** This promise type was introduced in CFEngine 3.3.0 (2012). -**** +--- ## Attributes @@ -153,14 +153,14 @@ standard library. **Allowed input range:** (arbitrary string)|(menu_option) depending on `service_type` -* When `service_type` is `windows` allowed values are limited to `start`, `stop`, `enable`, or `disable`. - * **start|enable** :: Will start the service if it is not running. - **Startup Type** will be set to **Manual** if it is not **Automatic** or **Automatic (Delayed Start)**. - For a service to be configured to start automatically on boot a `service_method` must be declared and `service_autostart_policy` must be set to `boot_time`. - * **stop** :: Will stop the service if it is running. **Startup Type** will not be modified unless a `service_method` is declared and `service_autostart_policy` is set. - * **disable** :: Will stop the service if it is running, and **Startup Type** - will be set to **Disabled**. -* When `service_type` is `generic` any string is allowed and `service_bundle` is responsible for interpreting and implementing the desired state based on the `service_policy` value. +- When `service_type` is `windows` allowed values are limited to `start`, `stop`, `enable`, or `disable`. + - **start|enable** :: Will start the service if it is not running. + **Startup Type** will be set to **Manual** if it is not **Automatic** or **Automatic (Delayed Start)**. + For a service to be configured to start automatically on boot a `service_method` must be declared and `service_autostart_policy` must be set to `boot_time`. + - **stop** :: Will stop the service if it is running. **Startup Type** will not be modified unless a `service_method` is declared and `service_autostart_policy` is set. + - **disable** :: Will stop the service if it is running, and **Startup Type** + will be set to **Disabled**. +- When `service_type` is `generic` any string is allowed and `service_bundle` is responsible for interpreting and implementing the desired state based on the `service_policy` value. Historically `service_type` `generic` has supported `start`, `stop`, `enable`, `disable`, `restart` and `reload`. **Example:** @@ -251,7 +251,7 @@ bundle agent my_custom_service_method_DEB( service_identifier, desired_service_s **History:** -* Type changed from `menu_option` to `string` and allowed input range changed to +- Type changed from `menu_option` to `string` and allowed input range changed to arbitrary string from start|stop|enable|disable|restart|reload in CFEngine 3.10. Previously enable was mapped to start, disable was mapped to stop and reload was mapped to restart. @@ -293,7 +293,7 @@ services: `service_method` bodies have access to `$(this.promiser)` (the promised service) and `$(this.service_policy)` (the policy state the service should have). -**Notes:** `service_bundle` is not used when `service_type` is ```windows```. +**Notes:** `service_bundle` is not used when `service_type` is `windows`. **See also:** [Common body attributes][Promise types#Common body attributes] @@ -358,8 +358,8 @@ inetd or xinetd on Unix. **Description:** The agent bundle to use when managing the service. -**Default:** The canonified promiser string prefixed with ```service_```. Note, -the ```service_bundle``` **must** be in the same namespace. +**Default:** The canonified promiser string prefixed with `service_`. Note, +the `service_bundle` **must** be in the same namespace. **Type:** `bundle agent` @@ -437,4 +437,4 @@ body service_method example **Notes:** On Windows this defaults to, and must be `windows`. Unix systems can however have multiple means of registering services, but the choice must be available on the given system. `service_bundle` is not used when `service_type` -is ```windows```. +is `windows`. diff --git a/content/reference/promise-types/storage.markdown b/content/reference/promise-types/storage.markdown index 57027a2a7..21dd091ed 100644 --- a/content/reference/promise-types/storage.markdown +++ b/content/reference/promise-types/storage.markdown @@ -43,7 +43,7 @@ body mount nfs(server,source) } ``` -*** +--- ## Attributes @@ -82,14 +82,15 @@ body mount example **Type:** (menu option) **Allowed input range:** + -* `nfs` -* `nfs2` -* `nfs3` -* `nfs4` -* `panfs` -* `cifs` +- `nfs` +- `nfs2` +- `nfs3` +- `nfs4` +- `panfs` +- `cifs` **Example:** @@ -97,7 +98,7 @@ body mount example **History:** -* `cifs`, `panfs` added in 3.15.0 +- `cifs`, `panfs` added in 3.15.0 #### mount_source diff --git a/content/reference/promise-types/users.markdown b/content/reference/promise-types/users.markdown index 6dd38cbeb..87c02001b 100644 --- a/content/reference/promise-types/users.markdown +++ b/content/reference/promise-types/users.markdown @@ -40,7 +40,7 @@ users: shell => "/bin/bash"; ``` -**** +--- ## Attributes diff --git a/content/reference/promise-types/vars.markdown b/content/reference/promise-types/vars.markdown index 28d05f6e2..c93fdc4af 100644 --- a/content/reference/promise-types/vars.markdown +++ b/content/reference/promise-types/vars.markdown @@ -200,7 +200,7 @@ contain the values copied from another `slist`, `rlist`, or `ilist`. See [`polic The `data` variables are obtained from functions that return data containers, such as `readjson()`, `readyaml()`, `parsejson()`, or `parseyaml()`, the various `data_*` functions, or from merging -existing data containers with `mergedata()`. They can *NOT* be +existing data containers with `mergedata()`. They can _NOT_ be modified, once created. ### Inline YAML and JSON data @@ -225,6 +225,7 @@ data early. Thus it is highly recommended that you try to avoid variable references in your inline JSON or YAML data. For example: + #### Inline Yaml example {{< CFEngine_include_example(inline-yaml.cf) >}} @@ -240,20 +241,20 @@ Data containers can be passed to another bundle with the ### Some useful tips for using data containers -* to extract just `container[x]`, use `mergedata("container[x]")` -* to wrap a container in an array, use `mergedata("[ container ]")` -* to wrap a container in a map, use `mergedata('{ "mykey": container }')` -* they act like "classic" CFEngine arrays in many ways -* `getindices()` and `getvalues()` work on any level, e.g. `getvalues("container[x][y]")` -* in reports, you have to reference a part of the container that can be expressed as a string. So for instance if you have the container `c` with data `{ "x": { "y": 50 }, "z": [ 1,2,3] }` we have two top-level keys, `x` and `z`. If you report on `$(c[x])` you will not get data, since there is no string there. But if you ask for `$(c[x][y])` you'll get `50`, and if you ask for `$(c[z])` you'll get implicit iteration on `1,2,3` (just like a slist in a "classic" CFEngine array). -* read the examples below carefully to see some useful ways to access data container contents +- to extract just `container[x]`, use `mergedata("container[x]")` +- to wrap a container in an array, use `mergedata("[ container ]")` +- to wrap a container in a map, use `mergedata('{ "mykey": container }')` +- they act like "classic" CFEngine arrays in many ways +- `getindices()` and `getvalues()` work on any level, e.g. `getvalues("container[x][y]")` +- in reports, you have to reference a part of the container that can be expressed as a string. So for instance if you have the container `c` with data `{ "x": { "y": 50 }, "z": [ 1,2,3] }` we have two top-level keys, `x` and `z`. If you report on `$(c[x])` you will not get data, since there is no string there. But if you ask for `$(c[x][y])` you'll get `50`, and if you ask for `$(c[z])` you'll get implicit iteration on `1,2,3` (just like a slist in a "classic" CFEngine array). +- read the examples below carefully to see some useful ways to access data container contents Iterating through a data container is only guaranteed to respect list order (e.g. `[1,3,20]` will be iterated in that order). Key order for maps, as per the JSON standard, is not guaranteed. Similarly, calling `getindices()` on a data container will give the list order of indices 0, 1, 2, ... but will not give the keys of a map in any particular -order. Here's an example of iterating in list order: +order. Here's an example of iterating in list order: {{< CFEngine_include_snippet(container_iteration.cf, #\+begin_src cfengine3, .*end_src) >}} @@ -297,7 +298,7 @@ vars: "inline2" data => '---$(const.n)- key2: value2'; # YAML requires "---$(const.n)" header ``` -*** +--- ## Attributes @@ -334,7 +335,7 @@ vars: **Notes:** -The policy `free` and `overridable` are synonyms. The policy `constant` is +The policy `free` and `overridable` are synonyms. The policy `constant` is deprecated, and has no effect. All variables are `free` or `overridable` by default which means the variables values may be changed. @@ -385,7 +386,7 @@ general rule which are described below. ### Meta type promises -Variables defined by the *meta* promise type are defined in a bundle scope with the same name as the executing bundle suffixed with ```meta```. +Variables defined by the _meta_ promise type are defined in a bundle scope with the same name as the executing bundle suffixed with `meta`. **Example policy:** @@ -489,7 +490,7 @@ R: { ### Module protocol -The module protocol allows specification of *context* (the bundle scope within which a variable gets defined). +The module protocol allows specification of _context_ (the bundle scope within which a variable gets defined). **Example policy:** @@ -526,7 +527,7 @@ R: { ### Augments -Augments defines variables in the *def* bundle scope. +Augments defines variables in the _def_ bundle scope. This augments file that defines `my_var` will be used for all examples shown here (`/tmp/def.json`). diff --git a/content/reference/special-variables/_index.markdown b/content/reference/special-variables/_index.markdown index 4e4c9bb1c..af28872d8 100644 --- a/content/reference/special-variables/_index.markdown +++ b/content/reference/special-variables/_index.markdown @@ -18,28 +18,28 @@ See `classes` for an explanation of the tags. CFEngine includes the following **special variables**: -* [connection][connection] -Variables defined for embedding unprintable values or values with special meanings -in strings. +- [connection][connection] + Variables defined for embedding unprintable values or values with special meanings + in strings. -* [const][const] -Variables defined for embedding unprintable values or values with special meanings -in strings. +- [const][const] + Variables defined for embedding unprintable values or values with special meanings + in strings. -* [edit][edit] -Variables used to access information about editing promises during their execution. +- [edit][edit] + Variables used to access information about editing promises during their execution. -* [match][match] -Variable used in string matching. +- [match][match] + Variable used in string matching. -* [mon][mon] -Variables defined in a monitoring context. +- [mon][mon] + Variables defined in a monitoring context. -* [sys][sys] -Variables defined in order to automate discovery of system values. +- [sys][sys] + Variables defined in order to automate discovery of system values. -* [def][def] -Variables with some default value that can be defined by [augments file][Augments] or in policy. +- [def][def] + Variables with some default value that can be defined by [augments file][Augments] or in policy. -* [this][this] -Variables used to access information about promises during their execution. +- [this][this] + Variables used to access information about promises during their execution. diff --git a/content/reference/special-variables/const.markdown b/content/reference/special-variables/const.markdown index 6de3cabff..e8e48a031 100644 --- a/content/reference/special-variables/const.markdown +++ b/content/reference/special-variables/const.markdown @@ -18,7 +18,7 @@ reports: **History:** -* Added in CFEngine 3.19.0, 3.18.1 +- Added in CFEngine 3.19.0, 3.18.1 ### const.dollar diff --git a/content/reference/special-variables/edit.markdown b/content/reference/special-variables/edit.markdown index 37f3317f4..576274bc9 100644 --- a/content/reference/special-variables/edit.markdown +++ b/content/reference/special-variables/edit.markdown @@ -25,8 +25,8 @@ bundle depending if the files prior content will or won't have any effect. **See also:** -* [empty_file_before_editing][files#empty_file_before_editing] in [edit_defaults bodies][files#edit_defaults]. +- [empty_file_before_editing][files#empty_file_before_editing] in [edit_defaults bodies][files#edit_defaults]. **History:** -* 3.21.0, 3.18.3 added +- 3.21.0, 3.18.3 added diff --git a/content/reference/special-variables/match.markdown b/content/reference/special-variables/match.markdown index 7edc444cb..a8886263d 100644 --- a/content/reference/special-variables/match.markdown +++ b/content/reference/special-variables/match.markdown @@ -4,7 +4,7 @@ title: match --- Each time CFEngine matches a string, these values are assigned to a special -variable context `$(match.`*n*`)`. The fragments can be referred to in the +variable context `$(match.`_n_`)`. The fragments can be referred to in the remainder of the promise. There are two places where this makes sense. One is in pattern replacement during file editing, and the other is in searching for files. diff --git a/content/reference/special-variables/sys.markdown b/content/reference/special-variables/sys.markdown index 21f80bf93..2dabff199 100644 --- a/content/reference/special-variables/sys.markdown +++ b/content/reference/special-variables/sys.markdown @@ -273,7 +273,7 @@ reports: "Tell me $(sys.hardware_mac[eth0])"; ``` -**Note:** The *keys* in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). +**Note:** The _keys_ in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). **History:** Was introduced in 3.3.0, Enterprise 2.2.0 (2011) @@ -933,17 +933,17 @@ Outputs: The following device flags are supported: -* up -* broadcast -* debug -* loopback -* pointopoint -* notrailers -* running -* noarp -* promisc -* allmulti -* multicast +- up +- broadcast +- debug +- loopback +- pointopoint +- notrailers +- running +- noarp +- promisc +- allmulti +- multicast **History:** Was introduced in 3.5.0 (2013) @@ -994,10 +994,10 @@ e.g. `$(sys.ip2iface[1.2.3.4])`. **Notes:** - The list of addresses may be acquired with `getindices("sys.ip2iface")` (or -from any of the other associative arrays). Only those interfaces which are -marked as "up" and have an IP address will have entries. + from any of the other associative arrays). Only those interfaces which are + marked as "up" and have an IP address will have entries. -- The *values* in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be `wlan0_1`. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). +- The _values_ in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be `wlan0_1`. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). **History:** Was introduced in 3.9. @@ -1045,19 +1045,19 @@ are marked as "up" and have an IP address will be listed. The first octet of the IPv4 address of the system interface named as the associative array index, e.g. `$(ipv4_1[le0])` or `$(ipv4_1[xr1])`. -**Note:** The *keys* in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). +**Note:** The _keys_ in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). ### sys.ipv4_2[interface_name] The first two octets of the IPv4 address of the system interface named as the associative array index, e.g. `$(ipv4_2[le0])` or `$(ipv4_2[xr1])`. -**Note:** The *keys* in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). +**Note:** The _keys_ in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). ### sys.ipv4_3[interface_name] The first three octets of the IPv4 address of the system interface named as the associative array index, e.g. `$(ipv4_3[le0])` or `$(ipv4_3[xr1])`. -**Note:** The *keys* in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). +**Note:** The _keys_ in this array are [canonified][canonify]. For example, the entry for `wlan0.1` would be found under the `wlan0_1` key. Ref: [CFE-4174](https://northerntech.atlassian.net/browse/CFE-4174). ### sys.key_digest @@ -1186,7 +1186,7 @@ R: Ubuntu **History:** -* 3.18.0 introduced +- 3.18.0 introduced ### sys.os_release @@ -1246,7 +1246,7 @@ R: 22 **History:** -* 3.18.0 introduced +- 3.18.0 introduced ### sys.ostype @@ -1271,7 +1271,7 @@ The name of the directory where CFEngine saves the daemon pid files. ### sys.policy_entry_basename The basename of the first policy file read by the agent. For example -```promises.cf``` or ```update.cf```. +`promises.cf` or `update.cf`. **See also:** [`sys.policy_entry_dirname`][sys.policy_entry_dirname] [`sys.policy_entry_filename`][sys.policy_entry_dirname] @@ -1282,7 +1282,7 @@ The basename of the first policy file read by the agent. For example ### sys.policy_entry_dirname The full path to the directory containing the first policy file read by the agent. For example -```/var/cfengine/inputs``` or ```~/.cfagent/inputs```. +`/var/cfengine/inputs` or `~/.cfagent/inputs`. **See also:** [`sys.policy_entry_basename`][sys#sys.policy_entry_basename] [`sys.policy_entry_filename`][sys.policy_entry_filename] @@ -1293,7 +1293,7 @@ The full path to the directory containing the first policy file read by the agen ### sys.policy_entry_filename The full path to the first policy file read by the agent. For example -```/var/cfengine/inputs/promises.cf``` or ```~/.cfagent/inputs/promises.cf```. +`/var/cfengine/inputs/promises.cf` or `~/.cfagent/inputs/promises.cf`. **See also:** [`sys.policy_entry_basename`][sys#sys.policy_entry_basename] [`sys.policy_entry_dirname`][sys#sys.policy_entry_dirname] @@ -1305,7 +1305,7 @@ The full path to the first policy file read by the agent. For example IP of the machine acting as the policy server. -```$(sys.workdir)/policy_server.dat``` stores bootstrap information. If bootstrapped to a hostname, the value is the current IP the hostname resolves to. If bootstrapped to an IP, the value is the stored IP. The variable is undefined if ```$(sys.workdir)/policy_server.dat``` does not exist or is empty. +`$(sys.workdir)/policy_server.dat` stores bootstrap information. If bootstrapped to a hostname, the value is the current IP the hostname resolves to. If bootstrapped to an IP, the value is the stored IP. The variable is undefined if `$(sys.workdir)/policy_server.dat` does not exist or is empty. ```cf3 reports: @@ -1320,10 +1320,10 @@ reports: ### sys.policy_hub_port -The default port which ```cf-agent``` will use by default when making outbound -connections to ```cf-serverd```. This defaults to ```5308``` but can be +The default port which `cf-agent` will use by default when making outbound +connections to `cf-serverd`. This defaults to `5308` but can be overridden based on the data provided during bootstrap stored in -```$(sys.workdir)/policy_server.dat```. +`$(sys.workdir)/policy_server.dat`. **History:** @@ -1398,7 +1398,7 @@ The name of the update policy file. ### sys.uptime A variable containing the number of minutes which the system has been -online. (Not implemented on the Windows platform.) +online. (Not implemented on the Windows platform.) ```cf3 # uptime = 69735 @@ -1504,4 +1504,5 @@ files (the directory name may change with the language of Windows): ```cf3 # workdir = C:\Program Files\CFEngine ``` + - diff --git a/content/reference/special-variables/this.markdown b/content/reference/special-variables/this.markdown index e1c25b333..f6ec7ab7d 100644 --- a/content/reference/special-variables/this.markdown +++ b/content/reference/special-variables/this.markdown @@ -68,13 +68,13 @@ to match multiple objects, the variable refers to the file that is currently making the promise. However, the variable can only be used in selected attributes: -* `transformer` -* `edit_template` -* [`source`][files#source] in `copy_from` -* `exec_program` in `file_select` -* class names in [`body classes`][Promise types#classes] -* logging attributes in [`body action`][Promise types#action] -* promised service name in `service_method` +- `transformer` +- `edit_template` +- [`source`][files#source] in `copy_from` +- `exec_program` in `file_select` +- class names in [`body classes`][Promise types#classes] +- logging attributes in [`body action`][Promise types#action] +- promised service name in `service_method` For example: @@ -125,7 +125,7 @@ and is always an integer. This variable refers to the `ppid` (parent process ID) of the `cf-agent` program. **Note:** This variable is reported by the platform dependent `getpid` function, -and is always an integer. On the Windows platform it's always 0. +and is always an integer. On the Windows platform it's always 0. ### this.service_policy @@ -152,8 +152,8 @@ the service methods. **See also:** -* `Services Bundles and Bodies` in the `Masterfiles Policy Framework standard - library` +- `Services Bundles and Bodies` in the `Masterfiles Policy Framework standard +library` ### this.this diff --git a/content/release-notes/_index.markdown b/content/release-notes/_index.markdown index 028fe70cc..36f793b69 100644 --- a/content/release-notes/_index.markdown +++ b/content/release-notes/_index.markdown @@ -4,11 +4,11 @@ title: Release notes sorting: 30 --- -* [New in CFEngine][New in CFEngine] +- [New in CFEngine][New in CFEngine] Learn about the newest features in CFEngine {{site.CFE_manuals_version}} -* [Supported platforms and versions][Supported platforms and versions] +- [Supported platforms and versions][Supported platforms and versions] These are the supported platforms for the current release. -* [Known issues][Known issues] +- [Known issues][Known issues] View any issues of which we are currently aware and investigating. View possible workarounds. diff --git a/content/release-notes/legal-and-licenses.markdown b/content/release-notes/legal-and-licenses.markdown index 13b5298c2..26e521cbf 100644 --- a/content/release-notes/legal-and-licenses.markdown +++ b/content/release-notes/legal-and-licenses.markdown @@ -28,90 +28,90 @@ CFEngine includes the following 3rd party libraries and components: These dependencies are used by both CFEngine Community (Open Source) as well as CFEngine Enterprise: -* [libacl](https://savannah.nongnu.org/projects/acl) under the [LGPL](https://git.savannah.gnu.org/cgit/acl.git/tree/include/acl.h) license -* [libattr](https://savannah.nongnu.org/projects/attr) under the [LGPL](https://git.savannah.gnu.org/cgit/attr.git/tree/include/libattr.h) license -* [libcurl](https://curl.se) under the [MIT/X derivative license](https://curl.se/docs/copyright.html) -* [libiconv](http://ftp.gnu.org/gnu/libiconv/) under the [LGPL](https://git.savannah.gnu.org/gitweb/?p=libiconv.git;a=blob;f=include/iconv.h.in) license -* [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/FAQ) under the [MIT license](https://opensource.org/license/mit/) -* [libyaml](https://pyyaml.org/wiki/LibYAML) under the [MIT license](https://github.com/yaml/libyaml/blob/master/License) -* [diffutils](https://ftpmirror.gnu.org/diffutils/) under the [GPLv3](https://git.savannah.gnu.org/cgit/diffutils.git/tree/src/diff.c) -* [LMDB](https://www.symas.com/lmdb) under the [OpenLDAP Public License](https://www.openldap.org/software/release/license.html) -* [OpenSSL](https://www.openssl.org) under the [OpenSSL (OpenSSL 1) or Apache v2 (OpenSSL 3) license](https://www.openssl.org/source/license.html) -* [PCRE](https://www.pcre.org) under the [PCRE license](https://www.pcre.org/licence.txt) or +- [libacl](https://savannah.nongnu.org/projects/acl) under the [LGPL](https://git.savannah.gnu.org/cgit/acl.git/tree/include/acl.h) license +- [libattr](https://savannah.nongnu.org/projects/attr) under the [LGPL](https://git.savannah.gnu.org/cgit/attr.git/tree/include/libattr.h) license +- [libcurl](https://curl.se) under the [MIT/X derivative license](https://curl.se/docs/copyright.html) +- [libiconv](http://ftp.gnu.org/gnu/libiconv/) under the [LGPL](https://git.savannah.gnu.org/gitweb/?p=libiconv.git;a=blob;f=include/iconv.h.in) license +- [libxml2](https://gitlab.gnome.org/GNOME/libxml2/-/wikis/FAQ) under the [MIT license](https://opensource.org/license/mit/) +- [libyaml](https://pyyaml.org/wiki/LibYAML) under the [MIT license](https://github.com/yaml/libyaml/blob/master/License) +- [diffutils](https://ftpmirror.gnu.org/diffutils/) under the [GPLv3](https://git.savannah.gnu.org/cgit/diffutils.git/tree/src/diff.c) +- [LMDB](https://www.symas.com/lmdb) under the [OpenLDAP Public License](https://www.openldap.org/software/release/license.html) +- [OpenSSL](https://www.openssl.org) under the [OpenSSL (OpenSSL 1) or Apache v2 (OpenSSL 3) license](https://www.openssl.org/source/license.html) +- [PCRE](https://www.pcre.org) under the [PCRE license](https://www.pcre.org/licence.txt) or [PCRE2](https://pcre2project.github.io/pcre2/) under the [PCRE2 license](https://github.com/PCRE2Project/pcre2/blob/master/LICENCE) -* [PEG](https://piumarta.com/software/peg/) under the [MIT license](https://opensource.org/license/mit/) -* [zlib](https://www.zlib.net) under the [zlib license](https://www.zlib.net/zlib_license.html) +- [PEG](https://piumarta.com/software/peg/) under the [MIT license](https://opensource.org/license/mit/) +- [zlib](https://www.zlib.net) under the [zlib license](https://www.zlib.net/zlib_license.html) ### Enterprise only dependencies In addition to the common dependencies listed above, these dependencies are specific to CFEngine Enterprise: -* [Angular.js](https://angularjs.org) under the [MIT license](https://github.com/angular/angular.js/blob/master/LICENSE) -* [Apache](https://httpd.apache.org) under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* [APR and APR-util](https://apr.apache.org) under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* [Chosen](https://harvesthq.github.io/chosen/) under the [MIT license](https://github.com/harvesthq/chosen/blob/master/LICENSE.md) -* [CodeIgniter](https://github.com/bcit-ci/CodeIgniter/) under the [MIT license](https://github.com/bcit-ci/CodeIgniter/blob/develop/license.txt) -* [Disphelper](https://disphelper.sourceforge.net) (only Windows) under the [BSD license](https://opensource.org/licenses/bsd-license.php) -* [Flot](https://www.flotcharts.org/) under the [MIT license](https://github.com/flot/flot/blob/master/LICENSE.txt) -* [Font Awesome](https://fontawesome.com/) by Dave Gandy - https://fontawesome.io/license/ -* [git](https://git-scm.com) under the [GNU General Public License, version 2 (GPLv2)](https://opensource.org/licenses/GPL-2.0) -* [Glyphicons](https://glyphicons.com/license/) under [Creative Commons Attribution 3.0 Unported (CC BY 3.0)](https://creativecommons.org/licenses/by-sa/3.0/deed.en_US) -* [HighCharts](https://www.highcharts.com/) under the [OEM license by HighSoft](https://shop.highcharts.com/) -* [jQuery](https://jquery.com/) under the [MIT license](https://opensource.org/license/mit/) -* [libexpat](https://sourceforge.net/projects/expat/) under the [MIT license](https://opensource.org/license/mit/) -* [libgnurx](http://www.gnu.org/software/rx/rx.html) under the [LGPLv2.1](https://github.com/TimothyGu/libgnurx/blob/libgnurx-2.5.1/regex.h) license -* [mod_ssl](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html) under a [BSD style license](http://www.modssl.org/docs/2.8/ssl_overview.html) -* [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php) under the [MIT license](https://github.com/bshaffer/oauth2-server-php/blob/develop/LICENSE) -* [OpenLDAP and liblber](https://www.openldap.org) under the [OpenLDAP Public License](https://www.openldap.org/software/release/license.html) -* [PHP](https://php.net) under the [PHP license](https://www.php.net/license/3_01.txt) -* [PostgreSQL](https://www.postgresql.org) under the [PostgreSQL License](https://opensource.org/licenses/postgresql) -* [rsync](https://rsync.samba.org) under the [GPLv3](https://rsync.samba.org/GPL.html) -* [Twitter Bootstrap Framework](https://getbootstrap.com) under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) -* [Bootstrap Icons](https://icons.getbootstrap.com) under the [MIT license](https://github.com/twbs/icons/blob/main/LICENSE) -* [underscore.js](https://underscorejs.org) under the [MIT license](https://opensource.org/license/mit/) -* [ace-builds](https://github.com/ajaxorg/ace-builds) under the [BSD-3-Clause](https://github.com/ajaxorg/ace-builds/blob/master/LICENSE) license -* [angular](http://angularjs.org) under the [MIT](https://github.com/angular/angular.js/blob/master/LICENSE) license -* [angular-chosen-localytics](http://github.com/leocaseiro/angular-chosen) under the [MIT](https://github.com/leocaseiro/angular-chosen/blob/master/LICENSE) license -* [angular-daterangepicker](https://github.com/fragaria/angular-daterangepicker) under the [MIT](https://github.com/fragaria/angular-daterangepicker/blob/master/LICENSE.md) license -* [angular-ui](https://github.com/buildium/angular-ui) under the [MIT](https://github.com/buildium/angular-ui/blob/master/LICENSE) license -* [bootstrap-multiselect](http://davidstutz.github.io/bootstrap-multiselect/) under the [Apache License, Version 2.0](http://davidstutz.github.io/bootstrap-multiselect/#license) -* [bootstrap-tour](http://bootstraptour.com) under the [MIT](https://github.com/sorich87/bootstrap-tour/blob/master/LICENSE) license -* [chosen-js](https://harvesthq.github.io/chosen/) under the [MIT](https://github.com/harvesthq/chosen/blob/master/LICENSE.md) license -* [clipboard](https://clipboardjs.com) under the [MIT](https://github.com/zenorocha/clipboard.js/blob/master/LICENSE) license -* [datatables](http://datatables.net) under the [MIT](https://datatables.net/license/mit) license -* [daterangepicker](https://github.com/dangrossman/daterangepicker) under the [MIT](https://github.com/dangrossman/daterangepicker/blob/master/README.md#license) license -* [google-code-prettify](https://www.npmjs.com/package/google-code-prettify) under the [Apache License 2.0](https://github.com/googlearchive/code-prettify/blob/master/COPYING) -* [highcharts](http://www.highcharts.com) under the [SLA](https://shop.highcharts.com/license) license -* [html5shiv](https://github.com/aFarkas/html5shiv#readme) under the [MIT license and GPL2](https://github.com/aFarkas/html5shiv/blob/master/MIT%20and%20GPL2%20licenses.md) -* [ip-subnet-calculator](https://github.com/franksrevenge/IPSubnetCalculator) under the [MIT](https://github.com/salieri/IPSubnetCalculator/blob/master/LICENSE) license -* [jquery](https://jquery.com) under the [MIT](https://github.com/salieri/IPSubnetCalculator/blob/master/LICENSE) license -* [jquery-appear-original](https://github.com/morr/jquery.appear) under the [MIT](https://github.com/morr/jquery.appear/blob/master/LICENSE) license -* [jquery-form](https://github.com/jquery-form/form) under the [MIT](https://github.com/jquery-form/form/blob/master/LICENSE) license -* [jquery-multiselect](https://github.com/techhysahil/jquery-MultiSelect) under the [MIT](https://github.com/techhysahil/jquery-MultiSelect/blob/master/LICENSE) license -* [jquery-ui-timepicker-addon](http://trentrichardson.com/examples/timepicker) under the [MIT](https://github.com/trentrichardson/jQuery-Timepicker-Addon?tab=License-1-ov-file) license -* [jquery-validation](https://jqueryvalidation.org/) under the [MIT](https://github.com/jquery-validation/jquery-validation/blob/master/LICENSE.md) license -* [jquery-wheelcolorpicker](https://raffer.one/projects/jquery-wheelcolorpicker) under the [MIT](https://github.com/fujaru/jquery-wheelcolorpicker/blob/master/LICENSE) license -* [jquery.cookie](https://github.com/carhartl/jquery-cookie) under the [MIT](https://github.com/carhartl/jquery-cookie/blob/master/MIT-LICENSE.txt) license -* [jquery.flot](https://www.npmjs.com/package/jquery.flot) under the [MIT](https://github.com/flot/flot/blob/master/LICENSE.txt) license -* [json2](http://github.com/SamuraiJack/JSON2/tree) under the [GNU Lesser General Public License](https://github.com/canonic-epicure/JSON2/blob/master/README.md#copyright-and-license) -* [jstimezonedetect](https://github.com/pellepim/jstimezonedetect) under the [MIT](https://github.com/pellepim/jstimezonedetect/blob/master/LICENCE.txt) license -* [notifyjs](https://notifyjs.jpillora.com/) under the [MIT](https://github.com/jpillora/notifyjs/blob/master/LICENSE) license -* [pluralize](https://github.com/blakeembrey/pluralize) under the [MIT](https://github.com/plurals/pluralize/blob/master/LICENSE) license -* [zxcvbn](https://github.com/dropbox/zxcvbn) under the [MIT](https://github.com/dropbox/zxcvbn/blob/master/LICENSE.txt) license -* [FPDF](http://www.fpdf.org/) under the [permissive license](https://github.com/Setasign/FPDF/blob/master/license.txt) -* [guzzle](https://docs.guzzlephp.org/) under the [MIT](https://docs.guzzlephp.org/en/stable/overview.html#license) license -* [tcpdf](https://tcpdf.org/) under the [GNU LESSER GENERAL PUBLIC LICENSE](https://tcpdf.org/docs/license/) -* [Slim](https://www.slimframework.com/) under the [MIT](https://github.com/slimphp/Slim/blob/4.x/LICENSE.md) -* [monolog](https://seldaek.github.io/monolog/) under the [MIT](https://github.com/Seldaek/monolog/blob/master/LICENSE) -* [LdapRecord](https://ldaprecord.com/) under the [MIT](https://github.com/DirectoryTree/LdapRecord/blob/master/license.md) -* [phpseclib](https://phpseclib.com/) under the [MIT](https://github.com/phpseclib/phpseclib/blob/master/LICENSE) -* [tonic](http://peej.github.com/tonic/) under the [MIT](https://github.com/peej/tonic/blob/master/LICENSE) +- [Angular.js](https://angularjs.org) under the [MIT license](https://github.com/angular/angular.js/blob/master/LICENSE) +- [Apache](https://httpd.apache.org) under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) +- [APR and APR-util](https://apr.apache.org) under the [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) +- [Chosen](https://harvesthq.github.io/chosen/) under the [MIT license](https://github.com/harvesthq/chosen/blob/master/LICENSE.md) +- [CodeIgniter](https://github.com/bcit-ci/CodeIgniter/) under the [MIT license](https://github.com/bcit-ci/CodeIgniter/blob/develop/license.txt) +- [Disphelper](https://disphelper.sourceforge.net) (only Windows) under the [BSD license](https://opensource.org/licenses/bsd-license.php) +- [Flot](https://www.flotcharts.org/) under the [MIT license](https://github.com/flot/flot/blob/master/LICENSE.txt) +- [Font Awesome](https://fontawesome.com/) by Dave Gandy - https://fontawesome.io/license/ +- [git](https://git-scm.com) under the [GNU General Public License, version 2 (GPLv2)](https://opensource.org/licenses/GPL-2.0) +- [Glyphicons](https://glyphicons.com/license/) under [Creative Commons Attribution 3.0 Unported (CC BY 3.0)](https://creativecommons.org/licenses/by-sa/3.0/deed.en_US) +- [HighCharts](https://www.highcharts.com/) under the [OEM license by HighSoft](https://shop.highcharts.com/) +- [jQuery](https://jquery.com/) under the [MIT license](https://opensource.org/license/mit/) +- [libexpat](https://sourceforge.net/projects/expat/) under the [MIT license](https://opensource.org/license/mit/) +- [libgnurx](http://www.gnu.org/software/rx/rx.html) under the [LGPLv2.1](https://github.com/TimothyGu/libgnurx/blob/libgnurx-2.5.1/regex.h) license +- [mod_ssl](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html) under a [BSD style license](http://www.modssl.org/docs/2.8/ssl_overview.html) +- [oauth2-server-php](https://github.com/bshaffer/oauth2-server-php) under the [MIT license](https://github.com/bshaffer/oauth2-server-php/blob/develop/LICENSE) +- [OpenLDAP and liblber](https://www.openldap.org) under the [OpenLDAP Public License](https://www.openldap.org/software/release/license.html) +- [PHP](https://php.net) under the [PHP license](https://www.php.net/license/3_01.txt) +- [PostgreSQL](https://www.postgresql.org) under the [PostgreSQL License](https://opensource.org/licenses/postgresql) +- [rsync](https://rsync.samba.org) under the [GPLv3](https://rsync.samba.org/GPL.html) +- [Twitter Bootstrap Framework](https://getbootstrap.com) under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0) +- [Bootstrap Icons](https://icons.getbootstrap.com) under the [MIT license](https://github.com/twbs/icons/blob/main/LICENSE) +- [underscore.js](https://underscorejs.org) under the [MIT license](https://opensource.org/license/mit/) +- [ace-builds](https://github.com/ajaxorg/ace-builds) under the [BSD-3-Clause](https://github.com/ajaxorg/ace-builds/blob/master/LICENSE) license +- [angular](http://angularjs.org) under the [MIT](https://github.com/angular/angular.js/blob/master/LICENSE) license +- [angular-chosen-localytics](http://github.com/leocaseiro/angular-chosen) under the [MIT](https://github.com/leocaseiro/angular-chosen/blob/master/LICENSE) license +- [angular-daterangepicker](https://github.com/fragaria/angular-daterangepicker) under the [MIT](https://github.com/fragaria/angular-daterangepicker/blob/master/LICENSE.md) license +- [angular-ui](https://github.com/buildium/angular-ui) under the [MIT](https://github.com/buildium/angular-ui/blob/master/LICENSE) license +- [bootstrap-multiselect](http://davidstutz.github.io/bootstrap-multiselect/) under the [Apache License, Version 2.0](http://davidstutz.github.io/bootstrap-multiselect/#license) +- [bootstrap-tour](http://bootstraptour.com) under the [MIT](https://github.com/sorich87/bootstrap-tour/blob/master/LICENSE) license +- [chosen-js](https://harvesthq.github.io/chosen/) under the [MIT](https://github.com/harvesthq/chosen/blob/master/LICENSE.md) license +- [clipboard](https://clipboardjs.com) under the [MIT](https://github.com/zenorocha/clipboard.js/blob/master/LICENSE) license +- [datatables](http://datatables.net) under the [MIT](https://datatables.net/license/mit) license +- [daterangepicker](https://github.com/dangrossman/daterangepicker) under the [MIT](https://github.com/dangrossman/daterangepicker/blob/master/README.md#license) license +- [google-code-prettify](https://www.npmjs.com/package/google-code-prettify) under the [Apache License 2.0](https://github.com/googlearchive/code-prettify/blob/master/COPYING) +- [highcharts](http://www.highcharts.com) under the [SLA](https://shop.highcharts.com/license) license +- [html5shiv](https://github.com/aFarkas/html5shiv#readme) under the [MIT license and GPL2](https://github.com/aFarkas/html5shiv/blob/master/MIT%20and%20GPL2%20licenses.md) +- [ip-subnet-calculator](https://github.com/franksrevenge/IPSubnetCalculator) under the [MIT](https://github.com/salieri/IPSubnetCalculator/blob/master/LICENSE) license +- [jquery](https://jquery.com) under the [MIT](https://github.com/salieri/IPSubnetCalculator/blob/master/LICENSE) license +- [jquery-appear-original](https://github.com/morr/jquery.appear) under the [MIT](https://github.com/morr/jquery.appear/blob/master/LICENSE) license +- [jquery-form](https://github.com/jquery-form/form) under the [MIT](https://github.com/jquery-form/form/blob/master/LICENSE) license +- [jquery-multiselect](https://github.com/techhysahil/jquery-MultiSelect) under the [MIT](https://github.com/techhysahil/jquery-MultiSelect/blob/master/LICENSE) license +- [jquery-ui-timepicker-addon](http://trentrichardson.com/examples/timepicker) under the [MIT](https://github.com/trentrichardson/jQuery-Timepicker-Addon?tab=License-1-ov-file) license +- [jquery-validation](https://jqueryvalidation.org/) under the [MIT](https://github.com/jquery-validation/jquery-validation/blob/master/LICENSE.md) license +- [jquery-wheelcolorpicker](https://raffer.one/projects/jquery-wheelcolorpicker) under the [MIT](https://github.com/fujaru/jquery-wheelcolorpicker/blob/master/LICENSE) license +- [jquery.cookie](https://github.com/carhartl/jquery-cookie) under the [MIT](https://github.com/carhartl/jquery-cookie/blob/master/MIT-LICENSE.txt) license +- [jquery.flot](https://www.npmjs.com/package/jquery.flot) under the [MIT](https://github.com/flot/flot/blob/master/LICENSE.txt) license +- [json2](http://github.com/SamuraiJack/JSON2/tree) under the [GNU Lesser General Public License](https://github.com/canonic-epicure/JSON2/blob/master/README.md#copyright-and-license) +- [jstimezonedetect](https://github.com/pellepim/jstimezonedetect) under the [MIT](https://github.com/pellepim/jstimezonedetect/blob/master/LICENCE.txt) license +- [notifyjs](https://notifyjs.jpillora.com/) under the [MIT](https://github.com/jpillora/notifyjs/blob/master/LICENSE) license +- [pluralize](https://github.com/blakeembrey/pluralize) under the [MIT](https://github.com/plurals/pluralize/blob/master/LICENSE) license +- [zxcvbn](https://github.com/dropbox/zxcvbn) under the [MIT](https://github.com/dropbox/zxcvbn/blob/master/LICENSE.txt) license +- [FPDF](http://www.fpdf.org/) under the [permissive license](https://github.com/Setasign/FPDF/blob/master/license.txt) +- [guzzle](https://docs.guzzlephp.org/) under the [MIT](https://docs.guzzlephp.org/en/stable/overview.html#license) license +- [tcpdf](https://tcpdf.org/) under the [GNU LESSER GENERAL PUBLIC LICENSE](https://tcpdf.org/docs/license/) +- [Slim](https://www.slimframework.com/) under the [MIT](https://github.com/slimphp/Slim/blob/4.x/LICENSE.md) +- [monolog](https://seldaek.github.io/monolog/) under the [MIT](https://github.com/Seldaek/monolog/blob/master/LICENSE) +- [LdapRecord](https://ldaprecord.com/) under the [MIT](https://github.com/DirectoryTree/LdapRecord/blob/master/license.md) +- [phpseclib](https://phpseclib.com/) under the [MIT](https://github.com/phpseclib/phpseclib/blob/master/LICENSE) +- [tonic](http://peej.github.com/tonic/) under the [MIT](https://github.com/peej/tonic/blob/master/LICENSE) ### Optional, non-default dependencies These dependencies are not a part of the packages we build and distribute, but specific users or customers may build CFEngine with support for custom functionality and with custom software dependencies: -* [libvirt](https://libvirt.org/) under the [LGPL version 2.1](https://www.opensource.org/licenses/lgpl-license.html) -* [QDBM](https://sourceforge.net/projects/qdbm/) under the [GNU Library or Lesser General Public License 2.0 (LGPLv2)](https://opensource.org/license/lgpl-2-1/) -* [TokyoCabinet](https://github.com/hthetiot/Tokyo-Cabinet) under the [GNU Lesser General Public License](https://www.opensource.org/licenses/lgpl-license.html) +- [libvirt](https://libvirt.org/) under the [LGPL version 2.1](https://www.opensource.org/licenses/lgpl-license.html) +- [QDBM](https://sourceforge.net/projects/qdbm/) under the [GNU Library or Lesser General Public License 2.0 (LGPLv2)](https://opensource.org/license/lgpl-2-1/) +- [TokyoCabinet](https://github.com/hthetiot/Tokyo-Cabinet) under the [GNU Lesser General Public License](https://www.opensource.org/licenses/lgpl-license.html) diff --git a/content/release-notes/supported-platforms.markdown b/content/release-notes/supported-platforms.markdown index b94fd1681..ff4883a18 100644 --- a/content/release-notes/supported-platforms.markdown +++ b/content/release-notes/supported-platforms.markdown @@ -11,30 +11,30 @@ for all supported platforms and [binary packages for popular Linux distributions ## Hub -| Platform | Versions | Architecture | -|:-----------:|:-------------------:|:------------:| -| CentOS/RHEL | 7, 8.1+, 9 | x86-64 | -| Debian | 11, 12 | x86-64 | -| Debian | 11, 12 | arm64 | -| Ubuntu | 20.04, 22.04, 24.04 | x86-64 | -| Ubuntu | 22.04, 24.04 | arm64 | +| Platform | Versions | Architecture | +| :---------: | :-----------------: | :----------: | +| CentOS/RHEL | 7, 8.1+, 9 | x86-64 | +| Debian | 11, 12 | x86-64 | +| Debian | 11, 12 | arm64 | +| Ubuntu | 20.04, 22.04, 24.04 | x86-64 | +| Ubuntu | 22.04, 24.04 | arm64 | Any supported host can be a policy server in Community installations of CFEngine. ## Clients -| Platform | Versions | Architectures | -|:-----------:|:-------------------:|:-------------:| -| AIX | 7.1, 7.2 | PowerPC | -| CentOS/RHEL | 7, 8.1+, 9 | x86-64 | -| Debian | 11, 12 | x86-64 | -| Debian | 11, 12 | arm64 | -| HP-UX | 11.31+ | Itanium | -| SLES | 12, 15 | x86-64 | -| Solaris | 11 | UltraSparc | -| Ubuntu | 20.04, 22.04, 24.04 | x86-64 | -| Ubuntu | 22.04, 24.04 | arm64 | -| Windows | 2012, 2016, 2019 | x86-64 | +| Platform | Versions | Architectures | +| :---------: | :-----------------: | :-----------: | +| AIX | 7.1, 7.2 | PowerPC | +| CentOS/RHEL | 7, 8.1+, 9 | x86-64 | +| Debian | 11, 12 | x86-64 | +| Debian | 11, 12 | arm64 | +| HP-UX | 11.31+ | Itanium | +| SLES | 12, 15 | x86-64 | +| Solaris | 11 | UltraSparc | +| Ubuntu | 20.04, 22.04, 24.04 | x86-64 | +| Ubuntu | 22.04, 24.04 | arm64 | +| Windows | 2012, 2016, 2019 | x86-64 | [Known issues][] also includes platform-specific notes. diff --git a/content/release-notes/whatsnew/_index.markdown b/content/release-notes/whatsnew/_index.markdown index 6f27a3754..b13ce6fb2 100644 --- a/content/release-notes/whatsnew/_index.markdown +++ b/content/release-notes/whatsnew/_index.markdown @@ -6,6 +6,6 @@ sorting: 10 See what's new in this release. -* [Core changelog][Changelog] -* [Enterprise changelog][Enterprise changelog] -* [Masterfiles changelog][Masterfiles changelog] +- [Core changelog][Changelog] +- [Enterprise changelog][Enterprise changelog] +- [Masterfiles changelog][Masterfiles changelog] diff --git a/content/resources/additional-topics/agility.markdown b/content/resources/additional-topics/agility.markdown index 5f74eb2fe..bcf7ea950 100644 --- a/content/resources/additional-topics/agility.markdown +++ b/content/resources/additional-topics/agility.markdown @@ -12,9 +12,9 @@ the wild, a climber on a rock-face or a wrestler engaged in combat, we identify the skills of anticipation, speed of response and the ability to adapt or bend without breaking to meet the challenges. -* Anticipate. -* Act. -* Adapt. +- Anticipate. +- Act. +- Adapt. In infrastructure management, agility represents the need to handle changing demand for service, to repair an absence of service, and to improve and deploy @@ -26,12 +26,12 @@ The compelling event that our system must respond to might represent danger, or merely a self-imposed deadline. In either case, there is generally a penalty associated with a lack of agility: a blow, a fall or a loss. -* What make agility possible? -* The capacity of a system -* Speed -* Precision -* Comprehension -* Efficiency +- What make agility possible? +- The capacity of a system +- Speed +- Precision +- Comprehension +- Efficiency ### What make agility possible? @@ -43,10 +43,10 @@ it. To respond to a challenge there are four stages that need attention: -* To comprehend the challenge. -* To solve the challenge. -* To respond to the challenge. -* To confirm or verify the response. +- To comprehend the challenge. +- To solve the challenge. +- To respond to the challenge. +- To confirm or verify the response. Each of these phases takes actual clock-time and requires a certain flexibility. Our goal is to keep these phases simple and therefore cheap for the long-term. @@ -69,21 +69,21 @@ maximum speed of a system within a single thread of activity2. Speed is the rate at which change takes place. For a configuration tool like CFEngine, speed can be measured either as -* Clock speed +- Clock speed - The actual elapsed wall-clock time-rate at which work gets done, including - any breaks and pauses in the schedule. + The actual elapsed wall-clock time-rate at which work gets done, including + any breaks and pauses in the schedule. - This depends on how often checks are made, or the interval between them, - e.g. in CFEngine, the default schedule is to verify promises every five - minutes. + This depends on how often checks are made, or the interval between them, + e.g. in CFEngine, the default schedule is to verify promises every five + minutes. -* System speed +- System speed - The average speed of the system when it is actually busy working on a - problem, excluding breaks and pauses. For example, once CFEngine has been - scheduled at the end of a five minute interval, it might take a few seconds - to make necessary changes. + The average speed of the system when it is actually busy working on a + problem, excluding breaks and pauses. For example, once CFEngine has been + scheduled at the end of a five minute interval, it might take a few seconds + to make necessary changes. Engineers can try to define an engineering scale of agility as the ratio of available speed to required speed and ratio of number ways a system can be @@ -118,10 +118,10 @@ bolster them with CFEngine's technology. For example: -* If we think in terms of services, it is the Service Level you have to achieve +- If we think in terms of services, it is the Service Level you have to achieve in order to comply with a Service Level Agreement. -* If we think of a support ticket, it is the speed we have to work at in order +- If we think of a support ticket, it is the speed we have to work at in order to keep the impact of an unpredicted change within acceptable levels. What we call /acceptable/ is a subjective judgement, i.e. a matter for policy to @@ -159,26 +159,26 @@ operational state. Acting quickly is not enough: we also need to be accurate in responding to change[^4]. We need to be able to: -* Model the desired outcome accurately in terms of universal policy coordinates: +- Model the desired outcome accurately in terms of universal policy coordinates: **Why**, **When**, **Where**, **What**, **How**. -* Maximize the chance that the promised outcome will be achieved. +- Maximize the chance that the promised outcome will be achieved. Precision is maximized when: -* Changes are _precise_, i.e. they can be made at a highly granular level, +- Changes are _precise_, i.e. they can be made at a highly granular level, without disturbing areas that are not relevant (few side-effects). -* Policy is able to model or describe the desired state accurately, i.e. within +- Policy is able to model or describe the desired state accurately, i.e. within the relevant area, the state is within acceptable tolerances. -* If any assumptions are hidden, they are describable in terms of the model, not +- If any assumptions are hidden, they are describable in terms of the model, not determined by the limitations of the software5. -* The agent executes the details of the model quickly and verifiably, in a +- The agent executes the details of the model quickly and verifiably, in a partially unpredictable environment, i.e. it should be fault tolerant. -* If the model cannot be implemented, it is possible to determine why and decide +- If the model cannot be implemented, it is possible to determine why and decide whether the problem lies in an incorrect assumption or a flaw in the implementation. @@ -193,8 +193,9 @@ The next challenge is concerns a human limitation. One of the greatest challenge Comprehensibility increases if something is predictable, or steady in its behaviour, but it decreases in proportion to the number of things we need to think about - which includes the many different contexts such as environments, or groups of machines with different purposes or profiles. Predictability (Reliability) Predictability - Comprehensibility =~ ---------------------------- = ---------------- - Contexts Diversity + +Comprehensibility =~ ---------------------------- = ---------------- +Contexts Diversity Our ability to comprehend behaviour depends on how predictable it is, i.e. how well it meets our expectations. For technology, we expect behaviour to be as close as possible on our intentions. CFEngine's maintenance of promises ensures that this is done with best possible effort and a rapid cycle of checking. @@ -230,45 +231,45 @@ Next: Agility in your work, Previous: Understanding agility, Up: Top We can now summarize some qualities of CFEngine that favour agility: -* Ability to express clear intentions about desired outcome (comprehension). +- Ability to express clear intentions about desired outcome (comprehension). -* Availability of insight into system performance and state (comprehension). +- Availability of insight into system performance and state (comprehension). -* Ability to manage large numbers of hosts and resources with a few generic +- Ability to manage large numbers of hosts and resources with a few generic patterns (efficiency). -* Ability to bundle related details into simple containers (comprehension +- Ability to bundle related details into simple containers (comprehension without loss of adaptability). -* Ability to accurately customize policy down to a low level without programming +- Ability to accurately customize policy down to a low level without programming (adaptability). -* Ability to recover quickly from faults and failures. The default, parallelized +- Ability to recover quickly from faults and failures. The default, parallelized execution framework verifies promises every 5 minutes for rapid fault detection and change deployment (clock speed)7 . -* A quick system monitoring/sampling rate - every 2.5 minutes (Nyquist +- A quick system monitoring/sampling rate - every 2.5 minutes (Nyquist frequency), for automated hands-free response to errors. -* Ability to recover cheaply. The lightweight resource footprint of CFEngine +- Ability to recover cheaply. The lightweight resource footprint of CFEngine that consumes few system resources required for actual business (system speed - low overhead, maximum capacity). -* Ability to increase number of clients without significant penalty (scalability +- Ability to increase number of clients without significant penalty (scalability and easy increase of capacity). -* A single framework for all devices and operating systems (ease of migrating +- A single framework for all devices and operating systems (ease of migrating from one platform to another). -* What agility means in different environments +- What agility means in different environments -* Separating What from How +- Separating What from How -* Packaging limits agility +- Packaging limits agility -* How abstraction improves agility +- How abstraction improves agility -* Increasing system capacity - by scaling +- Increasing system capacity - by scaling ### What agility means in different environments @@ -280,13 +281,13 @@ Users' expectations for agility can differ dramatically in the present; but if we think just a few years down the line, and follow the trends, it seems clear that limber systems must prevail in IT's evolutionary jungle. -* Desktop management -* Web shops -* Cloud providers -* High performance computing -* Government -* Finance -* Manufacturing +- Desktop management +- Web shops +- Cloud providers +- High performance computing +- Government +- Finance +- Manufacturing #### Desktop management @@ -544,10 +545,10 @@ data. You can also keep data outside your policy in databases, or sources like: -* LDAP -* NIS -* DNS -* System files +- LDAP +- NIS +- DNS +- System files For example, reading in data from a system file is very convenient. This is what Unix-like system do for passwords and user management. @@ -652,12 +653,12 @@ significant value. The rapid deployment of new services is assisted by: -* Virtualization hypervisor control or private cloud management (libvirt +- Virtualization hypervisor control or private cloud management (libvirt integration). -* Rapid, massively-parallelized custom configuration. +- Rapid, massively-parallelized custom configuration. -* Avoidance of network dependencies. +- Avoidance of network dependencies. Related to capacity is the issue of scaling services for massive available capacity. @@ -683,12 +684,12 @@ shall not discuss it further here. ## Agility in your work -* Easy versus simple -* How does complexity affect agility? -* An effective understanding helps agility -* Maximizing business imperatives -* What does agility cost? -* Who is responsible for agility? +- Easy versus simple +- How does complexity affect agility? +- An effective understanding helps agility +- Maximizing business imperatives +- What does agility cost? +- Who is responsible for agility? ### Easy versus simple @@ -699,10 +700,10 @@ but simple makes the future cost less. Easyis about barriers to adoption. If there is a cost associated with moving ahead that makes it hard: -* A psychological cost -* A cognitive cost -* It takes too long -* It costs too much money +- A psychological cost +- A cognitive cost +- It takes too long +- It costs too much money Simple is about what happens next. Once you have started, what happens if you want to change something? @@ -738,9 +739,9 @@ making a risky process _too easy_ can encourage haste and carelessness. Any problem has an intrinsic complexity, which can be measured by the smallest amount of information required to manage it, without loss of control. -* Ease is the absence of a barrier or cost to action. +- Ease is the absence of a barrier or cost to action. -* Simplicity is a strategy for minimizing Total Cost of Ownership. +- Simplicity is a strategy for minimizing Total Cost of Ownership. Making something truly simple is a very hard problem, but it is an investment in future change. What is easy today might be expensive to make easy tomorrow. But @@ -755,21 +756,21 @@ hurried deployment. Simplicity in CFEngine is addressed in the following ways: -* The software has few dependencies that complicate installation and upgrading. +- The software has few dependencies that complicate installation and upgrading. -* Changes made are atomic and minimize dependencies. +- Changes made are atomic and minimize dependencies. -* Each host works as an independent entity, reducing communication fragility. +- Each host works as an independent entity, reducing communication fragility. -* The configuration model is based on Promise Theory - a very consistent and +- The configuration model is based on Promise Theory - a very consistent and simple approach to modelling autonomous cooperative systems. -* All hosts run the same software agents on all operating platforms (from mobile +- All hosts run the same software agents on all operating platforms (from mobile phones to mainframes), and understand a single common language of intent, which they can translate into native system calls. So there are few exceptions to deal with. -* Comprehensive facilities are allowed for making use of patterns and other +- Comprehensive facilities are allowed for making use of patterns and other total-information-reducing tactics. A certain level of complexity might be necessary and desirable - complexity is @@ -872,34 +873,41 @@ term, by investing in knowledge management, speed and efficiency. Footnotes -[^1]: Capacity is often loosely referred to as _bandwidth_ because of its +[^1]: + Capacity is often loosely referred to as _bandwidth_ because of its connection to signal propagation in communication science, but this is not strictly correct, as bandwidth refers to parallel channels. -[^2]: For example, for a single coding frequency, the capacity of a +[^2]: + For example, for a single coding frequency, the capacity of a communications channel is measured in bits per second, and the bandwidth is the number multiplied by the number of parallel frequencies. -[^3]: If available speed matches need, and we have the capability to make all +[^3]: + If available speed matches need, and we have the capability to make all required changes, then we can claim exactly 100% agility. If we have less than required, then we get a smaller number, and if we have excess speed or changeability then we can even claim a super-efficiency. -[^4]: In the 20th century, science learned that there is no such thing as +[^4]: + In the 20th century, science learned that there is no such thing as determinism - the idea that you can guarantee an outcome absolutely. If you still think in such terms, you will be quickly disappointed. The best we can accomplish is to maximize the likelihood of a predictable result, relative to the kind of environment in which we work. -[^5]: In some other configuration software, assumptions are hard-coded into the +[^5]: + In some other configuration software, assumptions are hard-coded into the tools themselves, making the outcome undocumented. -[^6]: Other systems that claim to be deterministic simply stop with error +[^6]: + Other systems that claim to be deterministic simply stop with error messages. What is the correct behaviour? Clearly, this is a subjective choice. The important thing is that your system for change behaves in a predictable way. -[^7]: Two related concepts that are frequently referred to are the classic +[^7]: + Two related concepts that are frequently referred to are the classic reliability measures: Mean Time Before Failure (MTBF) or proactive health and Mean Time To Repair (MTTR), speed of recovery: (i) If we are proactive or quick at recovering from minor problems, larger outages can be avoided. @@ -910,12 +918,14 @@ Footnotes [^8]: See http://www.cfengine.com/blog/sysadmin-3.0-and-the-third-wave -[^9]: Service promises, as described here, were introduced into version 3.3.0 of +[^9]: + Service promises, as described here, were introduced into version 3.3.0 of CFEngine in 2012. [^10]: All good magic stories begin like this. -[^11]: Perhaps not just in the past. We are emerging from an industrial era of +[^11]: + Perhaps not just in the past. We are emerging from an industrial era of management where mass producing everything the same was the cheapest approach to scaling up services. However, today personal freedom demands variety and will not tolerate such oversimplification. diff --git a/content/resources/additional-topics/application-management.markdown b/content/resources/additional-topics/application-management.markdown index f068b86ff..f888f0ccf 100644 --- a/content/resources/additional-topics/application-management.markdown +++ b/content/resources/additional-topics/application-management.markdown @@ -27,25 +27,25 @@ properly customized for use. CFEngine assists with application management in a number of ways. Following the BDMA lifecycle, we note: -* Build +- Build - CFEngine can be used to automate the build of packaged software releases - using standardized or custom package formats. + CFEngine can be used to automate the build of packaged software releases + using standardized or custom package formats. -* Deploy +- Deploy - CFEngine can distribute and install packaged software on any kind of - platform. + CFEngine can distribute and install packaged software on any kind of + platform. -* Manage +- Manage - CFEngine can start, stop, restart, monitor, and upgrade, and customize - software applications. + CFEngine can start, stop, restart, monitor, and upgrade, and customize + software applications. -* Audit +- Audit - CFEngine can monitor and report on packages and patches installed on systems - and their versions and status. + CFEngine can monitor and report on packages and patches installed on systems + and their versions and status. ## Package management @@ -63,10 +63,10 @@ can download data from the network. Others have to have packages copied to local storage first. CFEngine can work with both types of system to integrate software management. -* CFEngine communicates with the system using its own standards to utilize the +- CFEngine communicates with the system using its own standards to utilize the approach suitable for that software system. -* Custom software repositories can be made, and CFEngine's agents can perform +- Custom software repositories can be made, and CFEngine's agents can perform this distribution by collecting software packages to local storage and then installing from there. @@ -178,10 +178,10 @@ packages: } ``` -By promising carefully what package and version you want, using package_policy, +By promising carefully what package and version you want, using package*policy, package_select, and package_version, CFEngine can keep this promise by updating to the latest version of the package available in the directory repository -/software_repo. If the available versions are all _less than_ than "1.0.0", an +/software_repo. If the available versions are all \_less than* than "1.0.0", an update will not take place. The package_version specification should match the versioning format of the software, whatever it is, e.g. you would write something like "1.00.00.0" if two digits were used in the two middle version diff --git a/content/resources/additional-topics/build-deploy-manage-audit.markdown b/content/resources/additional-topics/build-deploy-manage-audit.markdown index 0d64d86f9..fb3b3c00b 100644 --- a/content/resources/additional-topics/build-deploy-manage-audit.markdown +++ b/content/resources/additional-topics/build-deploy-manage-audit.markdown @@ -8,7 +8,7 @@ sorting: 80 The four mission phases are sometimes referred to as -* Build +- Build A mission is based on decisions and resources that need to be assembled or _built_ before they can be applied. This is the planning phase. @@ -18,7 +18,7 @@ The four mission phases are sometimes referred to as promises, the system will function seamlessly as planned. This is how it works in a human organization, and this is how is works for computers too. -* Deploy +- Deploy Deploying really means launching the policy into production. In CFEngine you simply publish your policy (in CFEngine parlance these are _promise proposals_) @@ -26,7 +26,7 @@ The four mission phases are sometimes referred to as Each machine runs an agent that is capable of keeping the system on course and maintaining it over time without further assistance. -* Manage +- Manage Once a decision is made, unplanned events will occur. Such incidents traditionally set off alarms and humans rush to make new transactions to @@ -34,7 +34,7 @@ The four mission phases are sometimes referred to as and humans only manage knowledge and have to deal with rare events that cannot be dealt with automatically. -* Audit +- Audit CFEngine performs continuous analysis and correction, and commercial editions generate explicit reports on mission status. Users can sit back and examine @@ -63,15 +63,15 @@ There are many approaches to building complete systems. When you use CFEngine, you should try to progress from thinking only about putting bytes on disks, to planning a long term set of promises to keep. -* What services do you want to support? +- What services do you want to support? -* What promises do you want to keep concerning these services? +- What promises do you want to keep concerning these services? -* Are these promises sustainable and convergently implementable? +- Are these promises sustainable and convergently implementable? -* Formulate proposed intentions in the form of CFEngine promises. +- Formulate proposed intentions in the form of CFEngine promises. -* Discuss the impact of these in your team of CFEngine Mission Specialists (more +- Discuss the impact of these in your team of CFEngine Mission Specialists (more than one pair of eyes). It is worth spending extra time in the build planning to simplify your system as @@ -98,29 +98,29 @@ Management). The following sequence forms a checklist for deploying successful policy change: -* Discuss the impact of changes in the team. +- Discuss the impact of changes in the team. -* Commit the changes to promises in version control, e.g. subversion. +- Commit the changes to promises in version control, e.g. subversion. -* Make a change in the CFEngine input files. +- Make a change in the CFEngine input files. -* Run the configuration through 'cf-promises --inform' to check for problems. +- Run the configuration through 'cf-promises --inform' to check for problems. -* Move the policy to a test system. +- Move the policy to a test system. -* Try running the configuration in dry-run model: 'cf-agent --dry-run' +- Try running the configuration in dry-run model: 'cf-agent --dry-run' -* Try running the policy once on a single system, being observant of unexpected - behaviour. +- Try running the policy once on a single system, being observant of unexpected + behaviour. -* Try running the policy on a small number of systems. +- Try running the policy on a small number of systems. -* Construct a test environment and examine the effect of these promises in - practice. +- Construct a test environment and examine the effect of these promises in + practice. -* Move the policy to the production environment. +- Move the policy to the production environment. -* If possible, test on one or a few machines before releasing for general use. +- If possible, test on one or a few machines before releasing for general use. CFEngine recommends a process of many small incremental changes, rather than large high-risk deployments. @@ -162,95 +162,95 @@ The reports CFEngine provides are meant to offer simple summaries of the kind of information administrators need about their environment, avoiding unnecessary detail. -* Available patches report +- Available patches report Patches already installed on system if available. -* Classes report +- Classes report User defined classes observed on the system - inventory data. -* Compliance report +- Compliance report Total summary of host compliance, all promises aggregated over time. -* File_changes report +- File_changes report Latest observed changes to system files with time discovered. -* File_diffs report +- File_diffs report Latest observed differences to system files, in a simple diff format. -* Hashes report +- Hashes report File hash values measured (change detection). -* Installed patches report +- Installed patches report Patches not yet installed, but published by vendor if available. -* Installed software report +- Installed software report Software already installed on system if available. -* Lastseen report +- Lastseen report Time and frequency of communications with peers, host reliability. -* Micro-audit report +- Micro-audit report Generated by CFEngine self-auditing. This report is not aggregated. -* Monitor summary report +- Monitor summary report Pseudo-real-time measurement of time series data. -* Performance report +- Performance report Time cost of verifying system promises. -* Promise report +- Promise report Per-promise average compliance report over time. -* Promises not kept report +- Promises not kept report Promises that were recently un-kept. -* Promises repaired report +- Promises repaired report Promises that were recently kept by repairing system state. -* Setuid report +- Setuid report Known setuid programs found on system. -* Variables report +- Variables report Current variable values expanded on different hosts. ## Summary BDMA workflow -* Define a stem cell host template. +- Define a stem cell host template. -* Set up PXE network booting and kickstart / jumpstart OS tools with CFEngine +- Set up PXE network booting and kickstart / jumpstart OS tools with CFEngine integrated. -* Get CFEngine running and updating on all hosts, but make no system changes. +- Get CFEngine running and updating on all hosts, but make no system changes. -* Define a service catalogue. +- Define a service catalogue. -* Discuss and formulate a policy increment, thinking convergence at all times. +- Discuss and formulate a policy increment, thinking convergence at all times. -* Publish (deploy) the policy. +- Publish (deploy) the policy. -* Follow emails and reports in the CFEngine Knowledge Map (Manage). +- Follow emails and reports in the CFEngine Knowledge Map (Manage). -* Adjust policy if necessary, following procedures for change management +- Adjust policy if necessary, following procedures for change management (Manage). -* View reports (or enjoy the silence) to audit system state. +- View reports (or enjoy the silence) to audit system state. CFEngine works well with package based management software. Users of rPath, for example, can achieve substantially improved efficiency in the build phase. diff --git a/content/resources/additional-topics/change-management.markdown b/content/resources/additional-topics/change-management.markdown index b45e6aff0..4f181a1f9 100644 --- a/content/resources/additional-topics/change-management.markdown +++ b/content/resources/additional-topics/change-management.markdown @@ -47,7 +47,7 @@ management reprisals, preferring to err on the side of caution, it is necessary to evaluate the best strategy for avoiding exposure to risk. To use automation effectively, it makes sense to separate change management into two phases: -* Change of policy itself - which defines desired state. +- Change of policy itself - which defines desired state. Policy has a strategic impact, and its change deserves a process that includes expert opinions, staged testing and ultimately a phased deployment during a @@ -82,9 +82,9 @@ is desirable to exercise due diligence in the design of a system's intended state, but we must be ready to quickly repair faults that might disrupt business services. We need to distinguish: -* Purposeful change of an intended policy (planning). +- Purposeful change of an intended policy (planning). -* Change in the actual system state and behaviour (implementation and +- Change in the actual system state and behaviour (implementation and maintenance). What is intended and what actually happens should not be confused. It is @@ -100,8 +100,8 @@ Time scales are crucially important in engineering, and deserve equal importance in IT management. Ask yourself: how do you know if something is changing or not? You've probably heard catchetisms such as: -* A watched kettle never boils. -* Tempus fugit (time flies). +- A watched kettle never boils. +- Tempus fugit (time flies). These phrases capture the idea that, if we expect to see change at a certain rate, it is possible to miss changes that occur at either a faster or slower @@ -381,19 +381,19 @@ handle incidents automatically, thus taking them off the list of things to worry about. Changes can introduce new incidents, so it is important to test changes to promises in advance. -* Formulate proposed intentions in the form of promises. +- Formulate proposed intentions in the form of promises. -* Discuss the impact of these in your team of CFEngine Mission Specialists (more +- Discuss the impact of these in your team of CFEngine Mission Specialists (more than one pair of eyes). -* Construct a test environment and examine the effect of these promises in +- Construct a test environment and examine the effect of these promises in practice. -* Commit the changes to promises in version control, e.g. subversion. +- Commit the changes to promises in version control, e.g. subversion. -* Deploy promises changes into live environment on a small number of machines. +- Deploy promises changes into live environment on a small number of machines. -* Finally deploy to all machines. +- Finally deploy to all machines. At each stage, we make careful, low-risk incursions on the system and see how it responds. Note that some side-effects could take days to emerge, so the schedule @@ -403,46 +403,49 @@ for change should account for the expected impact. The following sequence forms a checklist for deploying successful policy change: -* Discuss the impact of changes in the team. +- Discuss the impact of changes in the team. -* Construct a test environment and examine the effect of these promises in +- Construct a test environment and examine the effect of these promises in practice. -* Make a change in the CFEngine input files. +- Make a change in the CFEngine input files. -* Run the configuration through `cf-promises --inform` to check for problems. +- Run the configuration through `cf-promises --inform` to check for problems. -* Commit the tested changes to promises in version control, e.g. subversion. +- Commit the tested changes to promises in version control, e.g. subversion. -* Move the policy to a test system. +- Move the policy to a test system. -* Try running the configuration in dry-run model: `cf-agent --dry-run` +- Try running the configuration in dry-run model: `cf-agent --dry-run` -* Try running the policy once on a single system, being observant of unexpected +- Try running the policy once on a single system, being observant of unexpected behaviour. -* Try running the policy on a small number of systems. +- Try running the policy on a small number of systems. -* Move the policy to the production environment. +- Move the policy to the production environment. -* If possible, test on one or a few machines before releasing for general use. +- If possible, test on one or a few machines before releasing for general use. Be aware of the differences in your environment. A decision will not necessarily work everywhere in the same way. Footnotes -[^1]: For example, suppose a process runs out of control and starts filling up +[^1]: + For example, suppose a process runs out of control and starts filling up logs with error messages - the disk might fill up and cause a much more serious problem, such as a total system failure with crash, if this were left unattended. -[^2]: Nyquist's theorem is the main reason why CD-players sample at 44kHz in +[^2]: + Nyquist's theorem is the main reason why CD-players sample at 44kHz in order to cover the audible spectrum of 22kHz for most young people. Even though hearing deteriorates with age, and most people cannot hear this well, it provides a quality margin. -[^3]: Promise theory tells us that coordination requires mutual agreement +[^3]: + Promise theory tells us that coordination requires mutual agreement between all agents that work in a coordinated way on common resources. Every decision necessarily comes from a single point of origin (but there could be many of these, making non-overlapping decisions); consistency only starts to diff --git a/content/resources/additional-topics/cloud-computing.markdown b/content/resources/additional-topics/cloud-computing.markdown index 8ce32382e..ca8ec66d3 100644 --- a/content/resources/additional-topics/cloud-computing.markdown +++ b/content/resources/additional-topics/cloud-computing.markdown @@ -128,14 +128,14 @@ approach to continuous maintenance. The approach used by CFEngine is to: - * Help to bring comprehension to the scope of the problem (Knowledge Management - and Model-based Desired State Computing). +- Help to bring comprehension to the scope of the problem (Knowledge Management + and Model-based Desired State Computing). - * Help to implement change quickly and cheaply (through Lightweight - Automation). +- Help to implement change quickly and cheaply (through Lightweight + Automation). - * Help to bring measurable assurance about the state of compliance with policy - (continuous maintenance). +- Help to bring measurable assurance about the state of compliance with policy + (continuous maintenance). CFEngine's model promise-based computing provides both a language of assurance for keeping promises, and a measuring stick against which compliance can be @@ -143,16 +143,16 @@ measured. It is not necessary to make ad hoc judgements; every statement about the system can be documented and woven into a narrative about the system that can be understood both by technicians and management stakeholders. -* Deployment and maintaining real or virtual machines +- Deployment and maintaining real or virtual machines -* Instant Managed services from _stem cell_ hosts +- Instant Managed services from _stem cell_ hosts -* Modelling the required properties of all machines and allowing non-experts +- Modelling the required properties of all machines and allowing non-experts insight into that model to see how their business goals are being handled. -* Focus on outcomes rather than implementation. +- Focus on outcomes rather than implementation. -* Bring systems from any state into compliance. +- Bring systems from any state into compliance. ## What if I change my mind about Cloud Computing? diff --git a/content/resources/additional-topics/content-driven-policy.markdown b/content/resources/additional-topics/content-driven-policy.markdown index 64214137b..aa1f7ab67 100644 --- a/content/resources/additional-topics/content-driven-policy.markdown +++ b/content/resources/additional-topics/content-driven-policy.markdown @@ -78,15 +78,15 @@ that is needed. CFEngine provides Content-Driven Policies to cover mainstream management tasks like the following. -* File change/difference management -* Service management -* Database management -* Application / script management +- File change/difference management +- Service management +- Database management +- Application / script management ## How do content-driven policies work in detail? -The text files in masterfiles/cdp_inputs/(e.g. 'registry_list.txt') are parsed -into CFEngine lists by corresponding cdp_*files in masterfiles/(e.g. +The text files in masterfiles/cdp*inputs/(e.g. 'registry_list.txt') are parsed +into CFEngine lists by corresponding cdp*\*files in masterfiles/(e.g. 'cdp_registry.cf'). It is the latter set of files that actually implement the policies in the text files. diff --git a/content/resources/additional-topics/devops.markdown b/content/resources/additional-topics/devops.markdown index 604e9e311..5b59b90ae 100644 --- a/content/resources/additional-topics/devops.markdown +++ b/content/resources/additional-topics/devops.markdown @@ -287,6 +287,7 @@ bundle agent x ``` Results in: + ``` R: Hello a 1 x R: Hello b 1 x @@ -370,20 +371,20 @@ management. Integration of software components may be addressed with a variety of approaches and techniques: -* Standard template methods from the COPBL community library (_out of the box_ +- Standard template methods from the COPBL community library (_out of the box_ solutions). -* Customized, personalized configurations. +- Customized, personalized configurations. -* Package management for software dependencies. +- Package management for software dependencies. -* File management - copying, editing, permissions, etc. +- File management - copying, editing, permissions, etc. -* Process management - starting, stopping, restarting. +- Process management - starting, stopping, restarting. -* Security. +- Security. -* Monitoring performance and change. +- Monitoring performance and change. Needless to say, all of these are easily achievable with 5 minute repair accuracy using our CFEngine framework. diff --git a/content/resources/additional-topics/distributed-scheduling.markdown b/content/resources/additional-topics/distributed-scheduling.markdown index a037ab09b..5ff49c10c 100644 --- a/content/resources/additional-topics/distributed-scheduling.markdown +++ b/content/resources/additional-topics/distributed-scheduling.markdown @@ -19,9 +19,9 @@ on machine3. This is distributed scheduling. Dispatch is the term used for starting actually the execution of a job that has been scheduled. There are two ways to achieve distributed job scheduling: -* Centralized dispatch of jobs. +- Centralized dispatch of jobs. -* Peer to peer signalling with local dispatch of jobs. +- Peer to peer signalling with local dispatch of jobs. There are pros and cons to centralization. Centralization makes consistency easy to determine, but it creates bottlenecks in processing and allows one machine to @@ -37,18 +37,18 @@ in a secure fashion. You promise to execute tasks or keep promises at distributed places and times: -* You tell CFEngine what and how with the details of a promise. +- You tell CFEngine what and how with the details of a promise. -* You tell CFEngine where and when promises should be kept, using classes. +- You tell CFEngine where and when promises should be kept, using classes. CFEngine is designed principally to maintain desired state on a continuous basis. There are three cases for job scheduling: -* Unique jobs run once and only once. +- Unique jobs run once and only once. -* Standard jobs run sporadically on demand. +- Standard jobs run sporadically on demand. -* Standard jobs run on a regular schedule. +- Standard jobs run on a regular schedule. This list transfers to workflow processes too. If one job needs to follow after another (because it depends on it for something), we can ask if this workflow is @@ -157,9 +157,9 @@ To make a job happen at a specific time, we used a very specific time classifier 'Day24.January.Year2012.Hr16.Min45_50'. If we now want to make this workflow into a regular occurrence, repeating at some interval we have two options: -* We repeat this at the same time each week, day, hour, etc. +- We repeat this at the same time each week, day, hour, etc. -* We don't care about the precise time, we only care about the interval between +- We don't care about the precise time, we only care about the interval between executions. The checking of promises in CFEngine is controlled by classes and by ifelapsed diff --git a/content/resources/additional-topics/file-content.markdown b/content/resources/additional-topics/file-content.markdown index 61ea95cd8..60f26b2cf 100644 --- a/content/resources/additional-topics/file-content.markdown +++ b/content/resources/additional-topics/file-content.markdown @@ -50,21 +50,22 @@ the final destination by cf-agent. There are several ways to approach desired state management of file contents: - * Copy a finished file template to the desired location, completely overwriting - existing content. +- Copy a finished file template to the desired location, completely overwriting + existing content. - * Copy and adapt an almost finished template, filling in variables or macros to - yield a desired content. +- Copy and adapt an almost finished template, filling in variables or macros to + yield a desired content. - * Make corrections to whatever the existing state of the file might be. +- Make corrections to whatever the existing state of the file might be. There are advantages and disadvantages with each of these approaches and the best approach depends on the type of situation you need to describe. -For the approach Against the approach -1. Deterministic. Hard to specialize the result and the source must still be maintained by hand. -2. Deterministic. Limited specialization and must come from a single source, again maintained by hand. -3. Non-deterministic/partial model. Full power to customize file even with multiple managers. +For the approach Against the approach + +1. Deterministic. Hard to specialize the result and the source must still be maintained by hand. +2. Deterministic. Limited specialization and must come from a single source, again maintained by hand. +3. Non-deterministic/partial model. Full power to customize file even with multiple managers. Approaches 1 and 2 are best for situations where very few variations of a file are needed in different circumstances. Approach 3 is best when you need to @@ -75,26 +76,26 @@ is determined by them. ## Three approaches to managing files -* Copying a finished file template into place +- Copying a finished file template into place -* Contextual adaptation of a file template +- Contextual adaptation of a file template -* Example file template +- Example file template -* Combining copy with template expansion +- Combining copy with template expansion -* Making delta changes to someone else's file +- Making delta changes to someone else's file ### Copying a finished file template into place Use this approach if a simple substution of data will solve the problem in all contexts. -* Maintain the content of the file in a version controlled repository. +- Maintain the content of the file in a version controlled repository. -* Check out the file into a staging area. +- Check out the file into a staging area. -* Copy the file into place. +- Copy the file into place. ```cf3 bundle agent something @@ -111,14 +112,14 @@ files: There are several approaches here: -* Encode the boiler-plate template directly in the CFEngine configuration, and +- Encode the boiler-plate template directly in the CFEngine configuration, and have full use of the power of the CFEngine language to adapt it. -* Keep a separate boiler-plate file and edit/adapt it. +- Keep a separate boiler-plate file and edit/adapt it. -* Copy a template from a repository then edit/adapt it. +- Copy a template from a repository then edit/adapt it. -* Copy a generic template with embedded variables that can be expanded like +- Copy a generic template with embedded variables that can be expanded like macro-substitution. Choose the approach that you consider to be simplest and most reliable for the @@ -718,9 +719,9 @@ insert_lines: } ``` -* Standard library methods for simple editing +- Standard library methods for simple editing -* Expressing expand_template as promises +- Expressing expand_template as promises ### Standard library methods for simple editing @@ -759,23 +760,23 @@ bundle agent example Some other examples of the standard editing methods are: -* append_groups_starting(v) -* append_if_no_line(str) -* append_if_no_lines(list) -* append_user_field(group,field,allusers) -* append_users_starting(v) -* comment_lines_containing(regex,comment) -* edit_line comment_lines_matching(regex,comment) -* delete_lines_matching(regex) -* expand_template(templatefile) -* insert_lines(lines) -* resolvconf(search,list) -* set_user_field(user,field,val) -* set_variable_values(v) -* set_variable_values2(v) -* uncomment_lines_containing(regex,comment) -* uncomment_lines_matching(regex,comment) -* warn_lines_matching(regex) +- append_groups_starting(v) +- append_if_no_line(str) +- append_if_no_lines(list) +- append_user_field(group,field,allusers) +- append_users_starting(v) +- comment_lines_containing(regex,comment) +- edit_line comment_lines_matching(regex,comment) +- delete_lines_matching(regex) +- expand_template(templatefile) +- insert_lines(lines) +- resolvconf(search,list) +- set_user_field(user,field,val) +- set_variable_values(v) +- set_variable_values2(v) +- uncomment_lines_containing(regex,comment) +- uncomment_lines_matching(regex,comment) +- warn_lines_matching(regex) You find these in the documentation for the COPBL. @@ -785,14 +786,14 @@ As on CFEngine 3.3.0, CFEngine has a new template mechanism to make it easier to encode complex file templates. These templates map simply to edit_line bundles in the following way. -* Each line in a template maps to a separate insert_lines promise unless it is +- Each line in a template maps to a separate insert_lines promise unless it is grouped with '[%CFEngine BEGIN %]' and '[%CFEngine END %]' tags. -* Each multi-line group, marked with '[%CFEngine BEGIN %]' and +- Each multi-line group, marked with '[%CFEngine BEGIN %]' and '[%CFEngine END %]' tags maps to a multi-line insert_lines promise, with insert_type => "preserve_block". -* Each line that expresses a context-class: '[%CFEngine classexpression:: %]' +- Each line that expresses a context-class: '[%CFEngine classexpression:: %]' maps to a normal class expression in a bundle. The order of lines in the template is preserved within each block, or if @@ -816,11 +817,11 @@ There are two decisions to make when choosing how to manage file content: How can the desired content be constructed from the necessary source(s)? -* Is there more than one source of infromation that needs to be merged? +- Is there more than one source of infromation that needs to be merged? -* Do the contents need to be adapted to the specific environment? +- Do the contents need to be adapted to the specific environment? -* Is there context-specific information in the file? +- Is there context-specific information in the file? Use the simplest approach that requires the smallest number of promises to solve the problem. @@ -836,7 +837,7 @@ dependence as possible. Order dependence increases the fragility of maintainence, so you should do what you can to minimize it. -* Try to use substitution within a known template if order is important. +- Try to use substitution within a known template if order is important. The simplest kinds of files for configuration are line-based, with no special order. For such cases, simple line insertions are usually enough to configure diff --git a/content/resources/additional-topics/hierarchies.markdown b/content/resources/additional-topics/hierarchies.markdown index 9a6eacca2..6941844bf 100644 --- a/content/resources/additional-topics/hierarchies.markdown +++ b/content/resources/additional-topics/hierarchies.markdown @@ -143,6 +143,7 @@ linux.debian linux AND debian linux intersect debian ``` + ![Overlapping Sets](overlapping-sets.png) Sets can be made hierarchical when every subset is contained entirely by one and @@ -205,14 +206,14 @@ having a single-point of definition to avoid maintaining the same information in more than one place.This is an efficiency. Inheritance is expressed in different ways: - * Special subset extends base set properties, emphasizing that the leaf builds - on, or adds the root in order to extend it. +- Special subset extends base set properties, emphasizing that the leaf builds + on, or adds the root in order to extend it. - * Special subset inherits base set properties, emphasizing that the leaf is a - consumer of the root and does not necessarily offer any more. +- Special subset inherits base set properties, emphasizing that the leaf is a + consumer of the root and does not necessarily offer any more. - * Special subset depends on, emphasizing that the root is a single point of - failure for the leaf. +- Special subset depends on, emphasizing that the root is a single point of + failure for the leaf. These are basically equivalent expressions of the same thing. No matter how we choose to express this, inheritance is a client-server relationship in which a @@ -305,15 +306,15 @@ as CFEngine considers missing code to be a security issue and will signal an error for missing bundles. This is the default behaviour, but we can override it using the following body agent control promises. -* ignore_missing_bundles +- ignore_missing_bundles - Skip over any bundles listed in the bundlesequence constraint and continue - without error. + Skip over any bundles listed in the bundlesequence constraint and continue + without error. -* ignore_missing_inputs +- ignore_missing_inputs - Skip over any input files listed in the inputs contraint and continue - without error. + Skip over any input files listed in the inputs contraint and continue + without error. Be aware of the security implications of inheritance. Because of the assumption of authority, by promising to use the inheritance, you have subordinated your @@ -369,12 +370,12 @@ The keyt issue is: how tdo we slice and dice the cake into the largest pieces? In other words, what is that basic paradigm that you use to partition your system operations? Some alternatives include: -* Geographically (by site or country) -* By business department (sales, accounting, research) -* By security zone (private, DMZ, public, etc) -* By operating system (solaris, linux, darwin) -* By customer or client (e.g. for managed services) -* By task, service or role in the network (webservers, dns, workstations) +- Geographically (by site or country) +- By business department (sales, accounting, research) +- By security zone (private, DMZ, public, etc) +- By operating system (solaris, linux, darwin) +- By customer or client (e.g. for managed services) +- By task, service or role in the network (webservers, dns, workstations) However, you choose to begin, you can further subdivide these major categories by simply ANDing with other categories. diff --git a/content/resources/additional-topics/iteration.markdown b/content/resources/additional-topics/iteration.markdown index 93a94b9d9..548415869 100644 --- a/content/resources/additional-topics/iteration.markdown +++ b/content/resources/additional-topics/iteration.markdown @@ -368,7 +368,7 @@ R: mon.dev_smtp_out is $(mon.dev_smtp_out) In this case, all we are doing is creating an array called `io_vars`. Note that the indices of the elements of the array are iterated from two lists, so in this -case we'll have 2*3 = 6 elements in the array, covering all the combinations of +case we'll have 2\*3 = 6 elements in the array, covering all the combinations of the two lists inout and inout-names. The values of the array elements can be whatever we like. In this case, we're @@ -479,7 +479,7 @@ In this example, we create a two arrays (io_vars and n_vars), and a number of lists (but the most important ones are stats and monvars). We have but a single report promise, but it iterates over these latter two lists. With only a single reports promise and intelligent use of lists and arrays, we are able to report -on every one of the 3*(8+2*18+4*2)==156 monitor variables. And to change the +on every one of the 3*(8+2*18+4\*2)==156 monitor variables. And to change the format of every report, we will only have a single statement to change. ## Summary of iteration diff --git a/content/resources/additional-topics/itil.markdown b/content/resources/additional-topics/itil.markdown index 3cdfb8cd2..32d2cb3c7 100644 --- a/content/resources/additional-topics/itil.markdown +++ b/content/resources/additional-topics/itil.markdown @@ -34,8 +34,7 @@ improvements and enhancements. Today, the most popular release of ITIL is given by the books of ITIL version 2 (often referred to as ITILv2), while the British OGC (Office of Government Commerce), owner and publisher of ITIL, is currently promoting ITIL version 3 (ITILv3) under the device `"ITIL Reloaded"`. A further -ITIL version has already been planned, owing to perceived problems with version -3. +ITIL version has already been planned, owing to perceived problems with version 3. ITILv3 is not just an improved version of the ITILv2 books, but rather comes with a completely renewed structure, new sets of processes and a different scope @@ -50,22 +49,22 @@ quality improvement. Quality relates to the provided IT services as well as the management processes deployed to manage these services. Continual improvement in ITIL means to follow the method of Plan-Do-Check-Act: -* Plan +- Plan Plan the provision of high-quality IT services, i.e. set up the required management processes for the delivery and support of these services, define measurable goals and the course of action in order to fulfill them. -* Do +- Do Put the plans into action. -* Check +- Check Measure all relevant performance indicators, and quantify the achieved quality compared to the quality objectives. Check for potentials of improvement. -* Act +- Act In response to the measured quality, start activities for future improvements. This step leads into the Plan phase again. @@ -94,19 +93,19 @@ more substantiated idea of IT business alignment. Many version 2 processes and ideas have been recycled and extended by various additional processes and principles. The five service life cycle stages accordant to versin 3 are: - * Service Strategy: Common strategies and principles for customer-oriented, - business-driven service delivery and management +- Service Strategy: Common strategies and principles for customer-oriented, + business-driven service delivery and management - * Service Design: Principles and processes for the stage of designing new or - changed IT services +- Service Design: Principles and processes for the stage of designing new or + changed IT services - * Service Transition: Principles and processes to ensure quality-oriented - implementation of new or changed services into the operational environment +- Service Transition: Principles and processes to ensure quality-oriented + implementation of new or changed services into the operational environment - * Service Operation: Principles and processes for supporting service operation +- Service Operation: Principles and processes for supporting service operation - * Continual Service Improvement: Methods for planning and achieving service - improvements at regular intervals +- Continual Service Improvement: Methods for planning and achieving service + improvements at regular intervals ## Service orientation and ITIL @@ -133,23 +132,23 @@ is supposed to eliminate. To be able to use ITIL to help in this task, we have to first think of the process of setting up as a number of services. What services are these? We have to think a little sideways to see the relationship. -* Service Management +- Service Management Providing a sensible configuration policy, responding to discovered problems or the needs of end-users. -* Change Management +- Change Management A minor edit of the configuration policy, with appropriate quality controls. Or a change that comes from a completely different source, outside the scope of intended change. -* Release Management +- Release Management A new configuration policy, consisting of many changes. This could be a major and disruptive change so it should be planned carefully. -* Capacity Management +- Capacity Management Having enough resources for cfservd to answer all queries in a network. Having enough people and machines to support the processes of deploying and following @@ -159,62 +158,62 @@ services are these? We have to think a little sideways to see the relationship. The following management processes are in scope of ITILv3: -* Service Level Management: Management of Service Level Agreements (Alas), i.e. +- Service Level Management: Management of Service Level Agreements (Alas), i.e. service level and quality promises. -* Service Catalogue Management: deciding on the services that will be provided +- Service Catalogue Management: deciding on the services that will be provided and how they are advertised to users. -* Capacity Management: Planning and provision of adequate business, service and +- Capacity Management: Planning and provision of adequate business, service and resource capacities. -* Availability Management: Resource provision and monitoring of service, from a +- Availability Management: Resource provision and monitoring of service, from a customer viewpoint. -* Continuity Management: Development of strategies for dealing with potential +- Continuity Management: Development of strategies for dealing with potential disasters. -* Information Security Management: Ensuring a minimum level of information +- Information Security Management: Ensuring a minimum level of information security throughout the IT organization. -* Supplier Management: Maintaining supplier relationships. +- Supplier Management: Maintaining supplier relationships. -* Transition Planning and Support: Ensuring that new or changed services are +- Transition Planning and Support: Ensuring that new or changed services are deployed into the operational environment with the minimal impact on existing services -* Asset and Configuration Management: Management of IT assets and Configuration +- Asset and Configuration Management: Management of IT assets and Configuration Items. -* Release Management: Planning, building, testing and rolling out hardware and +- Release Management: Planning, building, testing and rolling out hardware and software configurations. -* Change Management: Assessment of current state, authorization and scheduling +- Change Management: Assessment of current state, authorization and scheduling of improvements. -* Service Validation and Testing: ensuring that services meet their specifications. +- Service Validation and Testing: ensuring that services meet their specifications. -* Knowledge Management: organizing and integrating experience and methodology +- Knowledge Management: organizing and integrating experience and methodology for future reference. -* Incident Management: responding to deviations from acceptable service. +- Incident Management: responding to deviations from acceptable service. -* Event Management: Efficient handling of service requests and complaints. +- Event Management: Efficient handling of service requests and complaints. -* Problem Management: Problem identification by trend analysis of incidents. +- Problem Management: Problem identification by trend analysis of incidents. -* Request Fulfillment: Fulfilling customer service requests. +- Request Fulfillment: Fulfilling customer service requests. -* Access Management: Management of access rights to information, services and +- Access Management: Management of access rights to information, services and resources. -* Service Strategy +- Service Strategy -* Service Design +- Service Design -* Service Operation +- Service Operation -* Continual Service Improvement +- Continual Service Improvement ### Service Strategy @@ -278,10 +277,10 @@ recent innovations can bridge the gap between the technology of distributed systems management and business-driven IT Service Management. To make the case we must show: -* How ITIL terminology relates to the terminology of CFEngine and hence to a +- How ITIL terminology relates to the terminology of CFEngine and hence to a traditional system administrator's language, and -* Which parts (processes and activities) of ITIL can be (partially) supported by +- Which parts (processes and activities) of ITIL can be (partially) supported by CFEngine, and how. ## Which ITIL processes apply to CFEngine? @@ -300,17 +299,17 @@ performance and quality for the process of continual improvement. Service support is composed of a number of issues: -* Incident management: collecting and dealing with incidents. +- Incident management: collecting and dealing with incidents. -* Problem management: root cause analysis and designing long term +- Problem management: root cause analysis and designing long term countermeasures. -* Configuration management: maintaining information about hardware and software +- Configuration management: maintaining information about hardware and software and their interrelationships. -* Change management: implementing major sequenced changes in the infrastructure. +- Change management: implementing major sequenced changes in the infrastructure. -* Release management: planning and implementing major "product" changes. +- Release management: planning and implementing major "product" changes. Although the difference between change management and release management is not completely clear in ITIL, we can think of a release as a change in the nature of @@ -319,11 +318,11 @@ within the scope of the same release. Thus is release is a more major change. Service delivery, on the other hand, is dissected as follows: -* Service Level Management -* Problem management -* Configuration management -* Change management -* Release management +- Service Level Management +- Problem management +- Configuration management +- Change management +- Release management These issues are somewhat clearer once we understand the usage of the terms "problem", "service" and "configuration". Once again, it is important that we @@ -335,19 +334,19 @@ In the world of business, reinvented through the eyes of ITIL's mentors, system administration and all its functions are wrapped in a model of service provision. -* ITIL Configuration Management (CM) -* CMDB Asset Management -* Change management in the enterprise -* Change management vs convergence -* Release management -* Incident and problem management -* Service Level Management (SLM) +- ITIL Configuration Management (CM) +- CMDB Asset Management +- Change management in the enterprise +- Change management vs convergence +- Release management +- Incident and problem management +- Service Level Management (SLM) ### ITIL Configuration Management (CM) Perhaps the most obvious example is the term configuration management. -* Configuration Management +- Configuration Management The process (and life-cycle) responsible for maintaining information about configuration items (CI) required to deliver an IT service, including their @@ -372,19 +371,19 @@ Since CFEngine is a completely distributed system that deals with individual devices on a one-by-one basis, we must interpret this asset management at two levels: -* The local assets of an individual device at the level of virtual structures +- The local assets of an individual device at the level of virtual structures and containers within it: files, attributes, software packages, virtual machines, processes etc. This is the traditional domain of automation for CFEngine's autonomic agent. -* The collective assets of a network of such devices. +- The collective assets of a network of such devices. Since a single host can be thought of as a network of assets connected through virtual pathways, it really isn't such a huge leap to see the whole network in a similar light. This is especially true when many of the basic resources are already shared objects, such as shared storage. -* CMDB Asset Management +- CMDB Asset Management Why bother to collect an inventory of this kind? Is it bureaucracy gone mad, or do we need it for insurance purposes? Both of these things are of course @@ -470,14 +469,14 @@ ITIL distinguishes betweenincidentsandproblems. An incident is an event that might be problematic, but in general would observe incidents over some length of time and then diagnoseproblemsbased on this experience. -* Incident +- Incident An event or occurrence that demands a response. One goal of CFEngine is to plan pro-actively to handle incidents automatically, thus taking them off the list of things to worry about. -* Problem +- Problem A pattern of consequence arising from certain incidents that is detrimental to the system. It is often a negative trend that needs to be addressed. @@ -498,12 +497,12 @@ promises. How does CFEngine fit into the management of a service organization? There are several ways: -* It offers a rapid detection and repair of faults that help to avoid formal +- It offers a rapid detection and repair of faults that help to avoid formal incidents. -* It simplifies the deployment (release) of services. +- It simplifies the deployment (release) of services. -* Allows resources to be understood and planned better. +- Allows resources to be understood and planned better. These properties allow for greaterpredictabilityof system services and therefore they contribute to customer confidence. @@ -527,16 +526,16 @@ combined and made into a managementservice, with continuous service quality. CFEngine can assist with: -* Maintenance assurance. -* Reporting for auditing. -* Change management. -* Security verification. +- Maintenance assurance. +- Reporting for auditing. +- Change management. +- Security verification. Promise theory comes with a couple of principles: -* Separation of concerns. +- Separation of concerns. -* Fundamental attention to autonomy of parts. +- Fundamental attention to autonomy of parts. Other approaches to discussing organization talk about the separation of concerns, so why is promise theory special? Object Orientation (OO) is an diff --git a/content/resources/additional-topics/modularity.markdown b/content/resources/additional-topics/modularity.markdown index 16438aeea..690548cce 100644 --- a/content/resources/additional-topics/modularity.markdown +++ b/content/resources/additional-topics/modularity.markdown @@ -440,15 +440,15 @@ where order is important. In re-designing CFEngine, we have taken a pragmatic approach to ordering. Essentially, CFEngine takes care of ordering for you for most cases - and you can override the order in three ways: - * CFEngine checks promises of the same type in the order in which they are - defined, unless overridden +- CFEngine checks promises of the same type in the order in which they are + defined, unless overridden - * Bulk ordering of composite promises (called bundles) is handled using an - overall list using the bundlesequence (replaces the actionsequence in - previous CFEngines) +- Bulk ordering of composite promises (called bundles) is handled using an + overall list using the bundlesequence (replaces the actionsequence in + previous CFEngines) - * Dependency coupling through dynamic classes, may be used to guarantee - ordering in the few cases where this is required, as in the example below: +- Dependency coupling through dynamic classes, may be used to guarantee + ordering in the few cases where this is required, as in the example below: ## Bundle ordering @@ -561,9 +561,9 @@ decentralized approach to coordinating activities across multiple hosts. Some tools try to approach this by centralizing data from the network in a single location, but this has two problems: - * It leads to a bottleneck by design that throttles performance seriously. +- It leads to a bottleneck by design that throttles performance seriously. - * It relies on the network being available. +- It relies on the network being available. With CFEngine Nova there are are both decentralized network approaches to this problem, and probabilistic methods that do not require the network at all. @@ -1177,11 +1177,13 @@ file_to_print => "$(file)"; number_of_lines => "10"; } ``` + When executed, this produces output only on the final host in the chain, showing the correct ordering out operations. The sequence also passes a file from host to host as a coordination token, like a baton in a relay race, and each host signs this so that the final host has a log of every host involved in the cascade. + ``` R: Singing the overture... R: Singing the first adagio... @@ -1446,9 +1448,11 @@ file_to_print => "$(file)"; number_of_lines => "100"; } ``` + Let's test it on a single host, equipped with aliases to the see entire flow. Without the trigger, this simply yields + ``` R: Done host1 R: Done host2 diff --git a/content/resources/additional-topics/open-nebula.markdown b/content/resources/additional-topics/open-nebula.markdown index 1c55d0a0c..268bc0b05 100644 --- a/content/resources/additional-topics/open-nebula.markdown +++ b/content/resources/additional-topics/open-nebula.markdown @@ -17,25 +17,25 @@ CFEngine is a lifecycle management tool that can be integrated with a Cloud Computing framework in a number of ways. Of the four phases of the computer lifecycle, Open Nebula and CFEngine will play different roles. -* Build +- Build Open Nebula focuses on building virtual machines in a managed framework, based on pre-built images. CFEngine can further customize these images through package of customized installation measures. -* Deploy +- Deploy Open Nebula provides manual controls to bring up and tear down generic virtualized machines containing a baseline of software. CFEngine can further deploy patches and updates to these basic images without needing to take down a machine. -* Manage +- Manage One a machine is running, CFEngine can manage it exactly like any other physical computer. -* Audit/Report +- Audit/Report CFEngine's local agents can extract information and learn system trends and characteristics over time. These may be collected in CFEngine's reporting @@ -51,10 +51,10 @@ This guide is based on an example setup provding a framework to demonstrate how CFEngine can be used to automate Open Nebula configuration. The following assumptions serve as an example and should be altered to fit your needs: -* All physical hosts are running Ubnutu, KVM and CFEngine 3. -* All physical hosts are on the same network. -* The CFEngine policy hub is running on the Open nebula front end. -* NFS will be used to share virtual machine images between hosts. +- All physical hosts are running Ubnutu, KVM and CFEngine 3. +- All physical hosts are on the same network. +- The CFEngine policy hub is running on the Open nebula front end. +- NFS will be used to share virtual machine images between hosts. Open nebula requires a single front-end machine and one or more node controllers. The front end is a management machine that is used to monitor and @@ -66,7 +66,7 @@ cluster-node. ![Open Nebula Architecture](./open-nebula-architecture.png) -### Installation and dependancy configuration +### Installation and dependancy configuration First we can classify the physical machines in this case by IP address: @@ -376,6 +376,7 @@ vars: "bridge_fd 0" }; ``` + Next we edit the interfaces file to include our new settings: ```cf3 diff --git a/content/resources/additional-topics/orchestration.markdown b/content/resources/additional-topics/orchestration.markdown index bb80d488d..6a8a518af 100644 --- a/content/resources/additional-topics/orchestration.markdown +++ b/content/resources/additional-topics/orchestration.markdown @@ -40,13 +40,13 @@ reorganize to outsource tasks are natural candidates for federated management. Promise theory predicts that a federated organization is naturally service oriented, with two main architectures: -* The different parts of the collective bind together by promising each other +- The different parts of the collective bind together by promising each other services. -* The parts offer services to external parties, but are bound together by +- The parts offer services to external parties, but are bound together by promising to coordinate with a central entity. -* Coordination, hierarchy and centralization +- Coordination, hierarchy and centralization Federated parts of an enterprise are said to be coordinated by an entity, if they receive common information from it. Merely delivering services (i.e. @@ -315,15 +315,15 @@ one of advice. Rules of thumb for scalable management: -* Use autonomy to scale: proximity to the affected area avoids unnecessary +- Use autonomy to scale: proximity to the affected area avoids unnecessary dependency and transport of materials. Trust costs less. -* If you need to enforce a common baseline (or constitution) for all, then +- If you need to enforce a common baseline (or constitution) for all, then arrange this as a service, not as a punitive force. Use local caching and the principal of convergence to a desired state (idempotence) to provide assurance without the cost of monitoring. -* Trust lowers costs. +- Trust lowers costs. ## The benefits of federated management diff --git a/content/resources/additional-topics/security.markdown b/content/resources/additional-topics/security.markdown index 25e3f266d..1878bcafe 100644 --- a/content/resources/additional-topics/security.markdown +++ b/content/resources/additional-topics/security.markdown @@ -26,8 +26,8 @@ machines, you might need several policy servers, i.e. several hubs. Any piece of software has two different architectures, which should not be confused: -* The information flow that results in decisions (weak coupling). -* The software or service dependence graph (strong coupling). +- The information flow that results in decisions (weak coupling). +- The software or service dependence graph (strong coupling). Information flow is about how users determine what promises the software should keep; this is entirely informational and once decisions are made they can be @@ -123,20 +123,20 @@ trusted and risky. CFEngine adheres to the following design principles: -* It shall be, by design, impossible to send policy-altering data to a CFEngine +- It shall be, by design, impossible to send policy-altering data to a CFEngine agent. Each host shall retain its right to veto policy suggestions at all times. This is called the Voluntary Cooperation Model. -* CFEngine will support the encyrption of data transmitted over the network. +- CFEngine will support the encyrption of data transmitted over the network. -* Each host shall continue to function, as far as possible, without the need for +- Each host shall continue to function, as far as possible, without the need for communication with other hosts. -* CFEngine will use a lightweight peer model for key trust (like the Secure +- CFEngine will use a lightweight peer model for key trust (like the Secure Shell). No centralized certificate authority shall be used. SSL and TLS shall not be used. -* CFEngine shall always provide safe defaults, that grant no access to other +- CFEngine shall always provide safe defaults, that grant no access to other hosts. ### Communications @@ -146,10 +146,11 @@ that used by OpenSSH (the free version of the Secure Shel). It is based on mutual, bi-directional challenge-reponse using an autonomous Public Key Infrastructure. - * Authentication by Public Key is mandatory. - * Encryption of data transfer is optional. +- Authentication by Public Key is mandatory. +- Encryption of data transfer is optional. ## Communication security + ### TCP wrappers The right to connect to the server is the first line of defence. CFEngine has @@ -161,36 +162,36 @@ non-authorized hosts the ability to connect to the server at all. A client attempts to connect to port 5308 Server examines IP address of connection and applies rules from -* allowconnects -* allowallconnects -* denyconnects +- allowconnects +- allowallconnects +- denyconnects -* If host is allowed to connect, read max 2048 bytes to look for valid hail -* Client sends its hostname, username and public key to server -* Server checks whether public key is known - * If known, host and user are confirmed, go to access control - * If unknown, use trustkeysfrom rules to check whether we should accept the +- If host is allowed to connect, read max 2048 bytes to look for valid hail +- Client sends its hostname, username and public key to server +- Server checks whether public key is known + - If known, host and user are confirmed, go to access control + - If unknown, use trustkeysfrom rules to check whether we should accept the client's asserted identity -* If not in trustkeysfrom list, break connection -* If willing to trust, go to further checks -* If skipverify is set, ignore reverse DNS lookup checks else check asserted +- If not in trustkeysfrom list, break connection +- If willing to trust, go to further checks +- If skipverify is set, ignore reverse DNS lookup checks else check asserted identity by reverse DNS lookup -* If fails break off -* Check user ID is in allowusers -* If fails break off -* Go to file access control -* Process admit first then deny -* Mapping of root privilege on server is governed by maproot. If this is false, only resources owned by the authenticated user name may be transmitted. -* If ifencrypted is set, access is denied to non-encrypted connections. -* Symbolic links to files are not honoured by the server when computing access. -* Access control is evaluated by the rules: - * First admit rule that matches wins - * All other admit rules are ignored - * No admit rule means you're denied! - * Then look at deny rules (overrides admit) - * First deny rule that matches wins - * All other deny rules are ignored - * No deny rule means you're admitted +- If fails break off +- Check user ID is in allowusers +- If fails break off +- Go to file access control +- Process admit first then deny +- Mapping of root privilege on server is governed by maproot. If this is false, only resources owned by the authenticated user name may be transmitted. +- If ifencrypted is set, access is denied to non-encrypted connections. +- Symbolic links to files are not honoured by the server when computing access. +- Access control is evaluated by the rules: + - First admit rule that matches wins + - All other admit rules are ignored + - No admit rule means you're denied! + - Then look at deny rules (overrides admit) + - First deny rule that matches wins + - All other deny rules are ignored + - No deny rule means you're admitted ### Encryption algorithms @@ -307,19 +308,19 @@ Our problem is to copy files from the "secure" source machine to hosts in the DMZ, in order to send them their configuration policy updates. There are two ways of getting files through the firewall: -* An automated CFEngine solution, i.e., pull from outside to inside the secure +- An automated CFEngine solution, i.e., pull from outside to inside the secure area. -* A manual push to the outside of the wall from the inside. +- A manual push to the outside of the wall from the inside. One of the main aims of a firewall is to prevent hosts outside the secure area from opening connections to hosts in the secure area. If we want cfagent processes on the outside of the firewall to receive updated policies from the inside of the firewall, information has to traverse the firewall. -* CFEngine trust model -* Policy mirror in the DMZ -* Pulling through a wormhole +- CFEngine trust model +- Policy mirror in the DMZ +- Pulling through a wormhole #### CFEngine trust model @@ -339,16 +340,16 @@ unacceptable (because they are conditioned to trust their firewall). But it is important to evaluate the actual risk. We have a few observations about the latter to offer at this point: -* It is not the aim of this note to advocate any one method of update. You must +- It is not the aim of this note to advocate any one method of update. You must decide for yourself. The aim here is only to evaluate the security implications. Exporting data from the secure area to the DMZ automatically downgrades the privacy of the information. -* The CFEngine security model assumes that the security of every host will be +- The CFEngine security model assumes that the security of every host will be taken seriously. A firewall should never be used as a substitute for host security. -* Knowing about CFEngine but not your firewall or your secure network, it is +- Knowing about CFEngine but not your firewall or your secure network, it is only possible to say here that it seems, to us, safe to open a hole in a firewall to download data from a host of our choice, but we would not accept data from just any host on your company network on trust. It would be diff --git a/content/resources/additional-topics/stigs.markdown b/content/resources/additional-topics/stigs.markdown index a63f6249f..3bdd7798f 100644 --- a/content/resources/additional-topics/stigs.markdown +++ b/content/resources/additional-topics/stigs.markdown @@ -50,14 +50,14 @@ PCI, SOX etc. Contact us through your regular CFEngine representative or use the contact form to learn how CFEngine can help you implement and achieve desired compliance. What are the different parts of this policy example? -* [STIGs.cf](./STIGs.cf) +- [STIGs.cf](./STIGs.cf) CFEngine policy file (ASCII), to be run by cf-agent -* [README](./STIGs_readme.txt) +- [README](./STIGs_readme.txt) Explanation of the various policy components (human readable), referencing - STIGs requirements id (such as ```GEN000560```) + STIGs requirements id (such as `GEN000560`) ## What are the terms of this STIGs example? diff --git a/content/resources/additional-topics/teamwork.markdown b/content/resources/additional-topics/teamwork.markdown index 02e316df4..1e56bc8df 100644 --- a/content/resources/additional-topics/teamwork.markdown +++ b/content/resources/additional-topics/teamwork.markdown @@ -42,31 +42,31 @@ M. Belbin, a researcher in teamwork has identified nine abilities or roles (kinds of promise) to be played in a team collaboration (regardless of how many people there are in the team): -* Plant - a creative "ideas" person who solves problems. +- Plant - a creative "ideas" person who solves problems. -* Shaper - this is a dynamic member of the team who thrives on pressure and has +- Shaper - this is a dynamic member of the team who thrives on pressure and has the drive and courage to overcome obstacles. -* Specialist - someone who brings specialist knowledge to the group. +- Specialist - someone who brings specialist knowledge to the group. -* Implementer - a practical thinker who is rooted in reality and can turn ideas +- Implementer - a practical thinker who is rooted in reality and can turn ideas into practice (who sometimes frustrates more imaginative high flying visionaries). -* Resource Investigator - an enabler, or someone who knows where to find the +- Resource Investigator - an enabler, or someone who knows where to find the help the team needs regardless of whether the help is physical, financial or human. This person is good at networking. -* Chairman/Co-ordinator - an arbitrator who makes sure that everyone gets their +- Chairman/Co-ordinator - an arbitrator who makes sure that everyone gets their say and can contribute. -* Monitor-Evaluator - is a dispassionate, discerning member who can judge +- Monitor-Evaluator - is a dispassionate, discerning member who can judge progress and achievement accurately during the process. -* Team Worker - someone concerned with the team's inter-personal relationships +- Team Worker - someone concerned with the team's inter-personal relationships and who is sensitive to the atmosphere of the group. -* Completer/Finisher - someone critical and analytical who looks after the +- Completer/Finisher - someone critical and analytical who looks after the details of presentation and spots potential flaws and gaps. The completer is a quality control person. @@ -112,18 +112,18 @@ allows us to model the collaborative security implications of this (see the figure of the bow-tie structure). A simple method of delegating is the following. -* Delegate responsibility for different issues to admin teams 1,2,3, etc. +- Delegate responsibility for different issues to admin teams 1,2,3, etc. -* Make each of these teams responsible for version control of their own +- Make each of these teams responsible for version control of their own configuration rules. -* Make an intermediate agent responsible for collating and vetting the rules, +- Make an intermediate agent responsible for collating and vetting the rules, checking for irregularities and conflicts. This agent must promise to disallow rules by one team that are the responsibility of another team. The agent could be a layer of software, but a cheaper and more manageable solution is the make this another group of one or more humans. -* Make the resulting collated configuration version controlled. Publish approved +- Make the resulting collated configuration version controlled. Publish approved promises for all hosts to download from a trusted source. A review procedure for policy-promises is a good solution if you want to diff --git a/content/resources/best-practices.markdown b/content/resources/best-practices.markdown index c30e7f750..1f12013c1 100644 --- a/content/resources/best-practices.markdown +++ b/content/resources/best-practices.markdown @@ -10,25 +10,25 @@ When writing CFEngine policy using our [Policy style guide][Policy style guide] ## Version control and configuration policy -CFEngine users version their policies. It's a reasonable, easy thing +CFEngine users version their policies. It's a reasonable, easy thing to do: you just put `/var/cfengine/masterfiles` under version control and... you're done? -What do you think? How do you version your own infrastructure? +What do you think? How do you version your own infrastructure? ### Problem statement It turns out everyone likes convenience and writing the versioning machinery is hard. So we provide version control integration with Git out of the box, disabled -by default. This allows users to use branches for separate hubs +by default. This allows users to use branches for separate hubs (which enables a policy release pipeline). ### Release pipeline A build and release pipeline is how software is typically delivered to -production through testing stages. In the case of CFEngine, policies -are the software. Users have at least two stages, development and +production through testing stages. In the case of CFEngine, policies +are the software. Users have at least two stages, development and production, but typically the sequence has more stages including various forms of testing/QA and pre-production. @@ -41,13 +41,14 @@ checked out and in minutes distributed through your entire infrastructure. ### Benefits -* easy to use compared to home-grown VCS integration -* supports Git out of the box and, with some work, can support others + +- easy to use compared to home-grown VCS integration +- supports Git out of the box and, with some work, can support others like Subversion, Mercurial, and CVS. -* tested, reliable, and built-in -* supports any repository and branch per hub -* your policies are validated before deployment -* integration happens through shell scripts and `update.cf`, not C +- tested, reliable, and built-in +- supports any repository and branch per hub +- your policies are validated before deployment +- integration happens through shell scripts and `update.cf`, not C code or special policies ### How to enable it @@ -66,10 +67,10 @@ Moving the PostgreSQL database to another physical hard drive from the other CFE The data access involves a huge number of random IO operations, with small chunks of data. SSD may give the best performance because it is designed for these types of scenarios. -*Important*: The PostgreSQL data files are in `/var/cfengine/state/pg/` by default. Before moving the mount point, please make sure that all CFEngine processes (including PostgreSQL) are stopped and the existing data files are copied to the new location. +_Important_: The PostgreSQL data files are in `/var/cfengine/state/pg/` by default. Before moving the mount point, please make sure that all CFEngine processes (including PostgreSQL) are stopped and the existing data files are copied to the new location. ### Setting the splaytime The `splaytime` tells CFEngine hosts the base interval over which they will communicate with the `policy server`, which they then use to "splay" or hash their own runtimes. -Thus when `splaytime` is set to 4, 1000 hosts will hash their run attempts evenly over 4 minutes, and each minute will see about 250 hosts make a run attempt. In effect, the hosts will attempt to communicate with the policy server and run their own policies in predictable "waves." This limits the number of concurrent connections and overall system load at any given moment. +Thus when `splaytime` is set to 4, 1000 hosts will hash their run attempts evenly over 4 minutes, and each minute will see about 250 hosts make a run attempt. In effect, the hosts will attempt to communicate with the policy server and run their own policies in predictable "waves." This limits the number of concurrent connections and overall system load at any given moment. diff --git a/content/resources/external-resources.markdown b/content/resources/external-resources.markdown index 328bd0f7d..32247c385 100644 --- a/content/resources/external-resources.markdown +++ b/content/resources/external-resources.markdown @@ -10,72 +10,72 @@ Use the following links to learn more about CFEngine: Learn by reading information brought to you by CFEngine experts: -* [Learning CFEngine](http://cf-learn.info/) by Diego Zamboni +- [Learning CFEngine](http://cf-learn.info/) by Diego Zamboni -* [CFEngine 3 Tutorial](http://watson-wilson.ca/2011/03/cfengine-3-tutorial.html) and -[Cookbook](http://watson-wilson.ca/cfengine/cf-cookbook/) by Neil Watson, a Senior -UNIX/Linux system admin and a [CFEngine Champion](https://cfengine.com/cfengine-champions-hall-of-fame). +- [CFEngine 3 Tutorial](http://watson-wilson.ca/2011/03/cfengine-3-tutorial.html) and + [Cookbook](http://watson-wilson.ca/cfengine/cf-cookbook/) by Neil Watson, a Senior + UNIX/Linux system admin and a [CFEngine Champion](https://cfengine.com/cfengine-champions-hall-of-fame). -* [CFEngine Resources](http://www.verticalsysadmin.com/cfengine.htm) by Vertical -Sysadmin, Inc, a sysadmin training company and an authorized CFEngine training partner. +- [CFEngine Resources](http://www.verticalsysadmin.com/cfengine.htm) by Vertical + Sysadmin, Inc, a sysadmin training company and an authorized CFEngine training partner. -* [CFEngine Development blog](http://cfengine.com/blog/tag/Development) Posts on -configuration management best practices from the CFEngine team. +- [CFEngine Development blog](http://cfengine.com/blog/tag/Development) Posts on + configuration management best practices from the CFEngine team. ## Training -* [Online Training](https://www.youtube.com/playlist?list=PLh71Vl9YjMajsWxT8zQuRKEPwosG9HdzV) An introduction to CFEngine by our founder, Mark Burgess. These video recordings explain the basic principles and syntax of the CFEngine language and suggests some examples to try out. +- [Online Training](https://www.youtube.com/playlist?list=PLh71Vl9YjMajsWxT8zQuRKEPwosG9HdzV) An introduction to CFEngine by our founder, Mark Burgess. These video recordings explain the basic principles and syntax of the CFEngine language and suggests some examples to try out. -* [Beyond Automation](http://shop.oreilly.com/product/110000787.do) Learn how to go beyond classical automation with CFEngine 3, one of the most established configuration management systems available. In this video tutorial, host and CFEngine creator Mark Burgess takes you on a tour of discovery from basic automation concepts to more complex examples, such as implementing distributed orchestration. +- [Beyond Automation](http://shop.oreilly.com/product/110000787.do) Learn how to go beyond classical automation with CFEngine 3, one of the most established configuration management systems available. In this video tutorial, host and CFEngine creator Mark Burgess takes you on a tour of discovery from basic automation concepts to more complex examples, such as implementing distributed orchestration. ## Tools -* [Editors with syntax support][Editors] +- [Editors with syntax support][Editors] ### Sign up -* [On-Site Training](https://cfengine.com/events) Sign up for professional training courses -that provide a better understanding of CFEngine and how it can help improve configuration -management in your organization. +- [On-Site Training](https://cfengine.com/events) Sign up for professional training courses + that provide a better understanding of CFEngine and how it can help improve configuration + management in your organization. -* [Contact us](http://info.cfengine.com/ContactUs.html) to get more info on training courses. +- [Contact us](http://info.cfengine.com/ContactUs.html) to get more info on training courses. ## Support and community ### Support desk -* [CFEngine Enterprise Support desk][support desk] Enterprise users have access to our support desk. +- [CFEngine Enterprise Support desk][support desk] Enterprise users have access to our support desk. ### Forums Help from our CFEngine community is available to all users on our Google Groups forums: -* [Support for CFEngine Enterprise users][Free25 Forum] Help for users who -have downloaded the free version of CFEngine 3 Enterprise. +- [Support for CFEngine Enterprise users][Free25 Forum] Help for users who + have downloaded the free version of CFEngine 3 Enterprise. -* [help-cfengine][help-cfengine] General help for all your CFEngine questions. +- [help-cfengine][help-cfengine] General help for all your CFEngine questions. ### Learning resources Sometimes the best help is already written. -* Visit our [learning resources][learning center] for guides, demos, training videos, and tools. +- Visit our [learning resources][learning center] for guides, demos, training videos, and tools. ### Social media Stay in touch. Follow us: -* [CFEngine blog][cfengine blog] +- [CFEngine blog][cfengine blog] -* LinkedIn +- LinkedIn -* Twitter +- Twitter -* Facebook +- Facebook -* The #CFEngine Matrix channel (#CFEngine:matrix.org). +- The #CFEngine Matrix channel (#CFEngine:matrix.org). If you want to learn more about how CFEngine can help you and your organization, [contact us][contact us]. @@ -84,12 +84,12 @@ organization, [contact us][contact us]. **CFEngine Github** -* [Code](https://github.com/cfengine/core) +- [Code](https://github.com/cfengine/core) -* [Documentation](https://github.com/cfengine/documentation) +- [Documentation](https://github.com/cfengine/documentation) **Public Bug Tracker** -* Bugs and improvement suggestions can be registered with our development team -in our [public bug tracker][bug tracker]. Read the bug tracker information before you -submit a bug. +- Bugs and improvement suggestions can be registered with our development team + in our [public bug tracker][bug tracker]. Read the bug tracker information before you + submit a bug. diff --git a/content/resources/faq/bootstrap-failed.markdown b/content/resources/faq/bootstrap-failed.markdown index 6ca3e6748..9d3c72364 100644 --- a/content/resources/faq/bootstrap-failed.markdown +++ b/content/resources/faq/bootstrap-failed.markdown @@ -23,7 +23,7 @@ To troubleshoot these types of errors review `cf-serverd` summary of access prom ### `cf-serverd` summary of access promises -cf-serverd provides a summary of access promises in *verbose* logs. Use this to see if `cf-serverd` is allowing access to the client. +cf-serverd provides a summary of access promises in _verbose_ logs. Use this to see if `cf-serverd` is allowing access to the client. Run cf-serverd with verbose logging and inspect the summary of access promises: @@ -118,9 +118,9 @@ verbose: === END summary of access promises === **Notes:** -* If the summary of access promises looks correct, it may be that `cf-serverd` has not reloaded with a new access rule. +- If the summary of access promises looks correct, it may be that `cf-serverd` has not reloaded with a new access rule. - Try stopping `cf-serverd` and starting it in the foreground with verbose logging (`cf-serverd --no-fork --log-level verbose`) and look for logs related to the client that was failing. + Try stopping `cf-serverd` and starting it in the foreground with verbose logging (`cf-serverd --no-fork --log-level verbose`) and look for logs related to the client that was failing. ### `allowconnects` in `body server control` @@ -128,11 +128,11 @@ In order for a host to communicate it must be within an IP range that is allowed `cf-serverd` logs errors when a host not in allow connects tries to communicate. -* `Remote host '' not in allowconnects, denying connection` +- `Remote host '' not in allowconnects, denying connection` **Notes:** -* `def.acl` in the Masterfiles Policy Framework is included in this list by default. +- `def.acl` in the Masterfiles Policy Framework is included in this list by default. See also: [`def.acl`][Masterfiles Policy Framework#acl], [`def.trustkeysfrom`][Masterfiles Policy Framework#trustkeysfrom] @@ -142,9 +142,9 @@ This defines networks from which a host will automatically trust hosts. If you d `cf-serverd` logs verbose and notice messages relating to un-trusted clients trying to connect: -* `notice: 192.168.56.4> TRUST FAILED, peer presented an untrusted key, dropping connection!` -* `verbose: 192.168.56.4> Did not find new key format '/var/cfengine/ppkeys/root-SHA=85f8a23d6738599e03951e6930e661bcd9bb3ae12f32486c9795cc9baa7d5b4e.pub'` -* `verbose: 192.168.56.4> Trying old style '/var/cfengine/ppkeys/root-192.168.56.4.pub'` -* `verbose: 192.168.56.4> Received key 'SHA=85f8a23d6738599e03951e6930e661bcd9bb3ae12f32486c9795cc9baa7d5b4e' not found in ppkeys` +- `notice: 192.168.56.4> TRUST FAILED, peer presented an untrusted key, dropping connection!` +- `verbose: 192.168.56.4> Did not find new key format '/var/cfengine/ppkeys/root-SHA=85f8a23d6738599e03951e6930e661bcd9bb3ae12f32486c9795cc9baa7d5b4e.pub'` +- `verbose: 192.168.56.4> Trying old style '/var/cfengine/ppkeys/root-192.168.56.4.pub'` +- `verbose: 192.168.56.4> Received key 'SHA=85f8a23d6738599e03951e6930e661bcd9bb3ae12f32486c9795cc9baa7d5b4e' not found in ppkeys` See also: [`def.acl`][Masterfiles Policy Framework#acl], [`def.trustkeysfrom`][Masterfiles Policy Framework#trustkeysfrom] diff --git a/content/resources/faq/enterprise-report-collection.markdown b/content/resources/faq/enterprise-report-collection.markdown index aeabf0a17..c7d82a82d 100644 --- a/content/resources/faq/enterprise-report-collection.markdown +++ b/content/resources/faq/enterprise-report-collection.markdown @@ -15,17 +15,18 @@ component may log to various data sources within `$(sys.statedir)`. ## How does CFEngine Enterprise collect reports? `cf-hub` makes connections from the hub to remote agents currently registered in -the lastseen database (viewable with ```cf-key -s```) +the lastseen database (viewable with `cf-key -s`) on [`body hub control port`][body hub control port] (5308 by default). The hub tries to collect from up to the LICENSED number of hosts for each collection round as identified by `hub_schedule` as defined in [`body hub control`][cf-hub#control-promises]. -* **See also:** `hostsseen()`, `hostswithclass()` +- **See also:** `hostsseen()`, `hostswithclass()` ## How often does cf-hub re-check the LICENSE + `cf-hub` re-checks the license when it is started and once every 5 minutes after that. @@ -63,6 +64,7 @@ When the number of hosts in the `lastseen` database (viewable with `cf-key -s`) is greater than the number of LICENSED hosts for this hub. ## How are agents not running determined? + Hosts who's last agent execution status is "FAIL" will show up under "Agents not running". A hosts last agent execution status is set to "FAIL" when the hub notices that there are no promise results within 3x of the expected agent run @@ -138,7 +140,7 @@ of oxygen, where oxygen is access to latest policy) to indicate a health issue. When a host is removed using the delete API its key is placed in a queue for trust revocation. To see which hosts are pending key removal use the following -query against the ```cfsettings``` database. +query against the `cfsettings` database. ```sql SELECT HostKey FROM KeysPendingForDeletion; @@ -152,7 +154,7 @@ reporting for hosts experiencing issues. ### Perform manual delta collection for a single host Performing back to back delta collections and comparing the data received can -help to expose so called *patching* issues. If the same amount of data is +help to expose so called _patching_ issues. If the same amount of data is collected twice a **rebase** may resolve it. ```console diff --git a/content/resources/faq/enterprise-report-filtering.markdown b/content/resources/faq/enterprise-report-filtering.markdown index 06656ad0a..16e60ffc3 100644 --- a/content/resources/faq/enterprise-report-filtering.markdown +++ b/content/resources/faq/enterprise-report-filtering.markdown @@ -36,6 +36,6 @@ The above policy can produce inventory that looks like this: ![inventoried list items](inventoried-list-items.png) -Adding a filter where "My Inventory" *matches* or *contains* ```common``` AND ```one```: +Adding a filter where "My Inventory" _matches_ or _contains_ `common` AND `one`: ![inventoried list items](filter-inventoried-list-items.png) diff --git a/content/resources/faq/enterprise.markdown b/content/resources/faq/enterprise.markdown index 54c6eaab7..fa57c92b2 100644 --- a/content/resources/faq/enterprise.markdown +++ b/content/resources/faq/enterprise.markdown @@ -26,12 +26,12 @@ The database runs under the `cfpostgres` user. ### General information -* [Pre-installation checklist][Pre-installation checklist] -* [Supported platforms and versions][Supported platforms and versions] +- [Pre-installation checklist][Pre-installation checklist] +- [Supported platforms and versions][Supported platforms and versions] ### Users and permissions -* CFEngine Enterprise makes an attempt to create the local users `cfapache` and +- CFEngine Enterprise makes an attempt to create the local users `cfapache` and `cfpostgres`, as well as group `cfapache` during install. ## How does Enterprise scale? @@ -40,7 +40,7 @@ See best practices on [scalability][Best practices#Scalability] ## Is it normal to have many cf-hub processes running? -* Yes, it is expected to have ~ 50 `cf-hub` processes running on a hub. +- Yes, it is expected to have ~ 50 `cf-hub` processes running on a hub. ## What steps should I take after installing CFEngine Enterprise? diff --git a/content/resources/faq/fhs.markdown b/content/resources/faq/fhs.markdown index 95bc3e68a..6daf87123 100644 --- a/content/resources/faq/fhs.markdown +++ b/content/resources/faq/fhs.markdown @@ -14,21 +14,22 @@ CFEngine was introduced at about the same time as the FHS standard and since cfengine 2.x, CFEngine defaults to placing all components under `/var/cfengine` (similar to `/var/cron`): -* `/var/cfengine` +- `/var/cfengine` -* `/var/cfengine/bin` +- `/var/cfengine/bin` -* `/var/cfengine/inputs` +- `/var/cfengine/inputs` -* `/var/cfengine/outputs` +- `/var/cfengine/outputs` Installing all components into the same sub-directory of `/var` is intended to -increase the probability that all components are on a *local* file system. This +increase the probability that all components are on a _local_ file system. This agrees with the intention of the FHS as described in section 5.1 of the FHS-2.3. The location of this workspace is configurable, but the default is determined by backward compatibility. In other words, particular distributions may choose to use a different location, and some do. References: + - https://lists.gnu.org/archive/html/help-cfengine/2004-09/msg00181.html - https://groups.google.com/d/msg/help-cfengine/q9jVopHatXI/M8asmeAWTxQJ diff --git a/content/resources/faq/fix-undefined-body-error.markdown b/content/resources/faq/fix-undefined-body-error.markdown index 9d8adee07..eac0bf807 100644 --- a/content/resources/faq/fix-undefined-body-error.markdown +++ b/content/resources/faq/fix-undefined-body-error.markdown @@ -7,6 +7,7 @@ sorting: 90 When running policy you see `error: Undefined body`. For example: `cf-promises -f ./large-files.cf`: + ``` ./large-files.cf:14:0: error: Undefined body tidy with type delete ./large-files.cf:16:0: error: Undefined body recurse with type depth_search diff --git a/content/resources/faq/integrate-custom-policy.markdown b/content/resources/faq/integrate-custom-policy.markdown index 44dbf6eea..58d51b979 100644 --- a/content/resources/faq/integrate-custom-policy.markdown +++ b/content/resources/faq/integrate-custom-policy.markdown @@ -16,9 +16,9 @@ Here we only describe ways to include and execute custom policies. ## Using autorun -The *autorun* feature in the Masterfiles Policy Framework automatically adds +The _autorun_ feature in the Masterfiles Policy Framework automatically adds policy files found in `services/autorun` to inputs and executes bundles tagged -with *autorun* as methods type promises in lexical order. +with _autorun_ as methods type promises in lexical order. **See also:** [`services_autorun` in the Masterfiles Policy Framework][Masterfiles Policy Framework#services\_autorun] @@ -53,55 +53,55 @@ To extend inputs in the update policy define `update_inputs`. ## Using body file control -*inputs* in `body file control` can be used to load additional policy files. +_inputs_ in `body file control` can be used to load additional policy files. This can be very useful for loading policy files that are relative to each other. **NOTES:** -- `body file control` can **not** be used to specify bundles that should be executed. -- `this.promise_*` variables can **not** be used directly in `body file control`. +- `body file control` can **not** be used to specify bundles that should be executed. +- `this.promise_*` variables can **not** be used directly in `body file control`. - ```cf3 - body file control - { - inputs => { "$(this.policy_dirname)/../stdlib.cf" }; - } - ``` +```cf3 +body file control +{ + inputs => { "$(this.policy_dirname)/../stdlib.cf" }; +} +``` Bundle variables can be used to achieve relative inputs. - ```cf3 - bundle common example_file_control - { - vars: - "policy[stdlib]" - string => "$(this.policy_dirname)/../my_other_policy.cf"; +```cf3 +bundle common example_file_control +{ + vars: + "policy[stdlib]" + string => "$(this.policy_dirname)/../my_other_policy.cf"; - "inputs" slist => getvalues( policy ); - } + "inputs" slist => getvalues( policy ); +} - body file control - { - inputs => { "$(example_file_control.inputs)" }; - } - ``` +body file control +{ + inputs => { "$(example_file_control.inputs)" }; +} +``` -- `sys.policy_*` variables **can** be used directly in `body file control`. +- `sys.policy_*` variables **can** be used directly in `body file control`. - ```cf3 - body file control - { - inputs => { "$(sys.policy_entry_dirname)/lib/stdlib.cf" }; - } - ``` +```cf3 +body file control +{ + inputs => { "$(sys.policy_entry_dirname)/lib/stdlib.cf" }; +} +``` **See also:** [`inputs` in `body file control`][file control#inputs] ## Using body common control `body common control` is the classic way to define the list of policy files that -make up the policy set ( *inputs* ), and the order of the bundles to be executed -( *bundlesequence* ). +make up the policy set ( _inputs_ ), and the order of the bundles to be executed +( _bundlesequence_ ). **See also:** [`inputs` in `body common control`][Components#inputs], [`bundlesequence` in `body common control`][Components#bundlesequence] diff --git a/content/resources/faq/manual-execution.markdown b/content/resources/faq/manual-execution.markdown index c3e3a6739..d64eea39a 100644 --- a/content/resources/faq/manual-execution.markdown +++ b/content/resources/faq/manual-execution.markdown @@ -63,7 +63,7 @@ Sometimes it's convenient to run `cf-execd` with `--once`. It will execute [defaults](https://github.com/cfengine/masterfiles/blob/{{site.cfengine.branch}}/controls/cf_execd.cf) to update policy ( `update.cf` ) followed by the default policy ( `promises.cf` ). Output from cf-execd executions is logged to -```$(sys.workdir)/outputs```. +`$(sys.workdir)/outputs`. # Request a remote agent run diff --git a/content/resources/faq/mustache-templating.markdown b/content/resources/faq/mustache-templating.markdown index e64e2e977..32e8276e1 100644 --- a/content/resources/faq/mustache-templating.markdown +++ b/content/resources/faq/mustache-templating.markdown @@ -8,10 +8,10 @@ sorting: 90 CFEngine has several extensions to the mustache standard. -* `-top-` special key representing the complete data given. -* `%` variable prefix causing data to be rendered as multi-line json representation. -* `$` variable prefix causing data to be rendered as compact json representation. -* `@` expands the current key being iterated. +- `-top-` special key representing the complete data given. +- `%` variable prefix causing data to be rendered as multi-line json representation. +- `$` variable prefix causing data to be rendered as compact json representation. +- `@` expands the current key being iterated. **See also:** [`template_method` `mustache` extensions][files#template_method mustache extensions] @@ -41,11 +41,11 @@ Version: CFEngine {{#classes.enterprise}}Enterprise{{/classes.enterprise}} {{var ## How do I render a section only if a given class is not defined? -In the mustache documentation this is referred to as an *inverted section*. +In the mustache documentation this is referred to as an _inverted section_. -In this mustache example the word ```Enterprise``` will only be rendered if the -class ```cfengine_enterprise``` is defined and the word ```Community``` will -only be rendered if the class ```cfengine_enterprise``` is not defined. +In this mustache example the word `Enterprise` will only be rendered if the +class `cfengine_enterprise` is defined and the word `Community` will +only be rendered if the class `cfengine_enterprise` is not defined. This template should not be passed a data container; it uses the `datastate()` of the CFEngine system. That's where `classes.cfengine_enterprise` and @@ -77,7 +77,7 @@ of the CFEngine system. That's where `vars.mon.listening_tcp4_ports` came from. ## How can I access keys when iterating over a dict? -In CFEngine, the `@` symbol expands to the current key when iterating over a dict. +In CFEngine, the `@` symbol expands to the current key when iterating over a dict. {{< CFEngine_include_example(mustache_extension_expand_key.cf) >}} diff --git a/content/resources/faq/show-classes-and-vars.markdown b/content/resources/faq/show-classes-and-vars.markdown index 46a897c27..526abcf52 100644 --- a/content/resources/faq/show-classes-and-vars.markdown +++ b/content/resources/faq/show-classes-and-vars.markdown @@ -12,8 +12,8 @@ filter the classes or variables. For example `cf-promises --show-classes=MT` will show all the classes that contain `MT` like `GMT_July`. You can see the variables and namespace scoped classes defined at the end of an -agent execution by using the ```--show-evaluated-vars``` or -```--show-evaluated-classes``` options to `cf-agent`. In addition to the +agent execution by using the `--show-evaluated-vars` or +`--show-evaluated-classes` options to `cf-agent`. In addition to the variables and classes shown by `cf-promises --show-classes` or `cf-promises --show-vars` this will show variables and namespace scoped classes that get defined during a full agent run where the system may be modified and more policy diff --git a/content/resources/faq/tuning-postgresql.markdown b/content/resources/faq/tuning-postgresql.markdown index dcbdb46b0..4d012e8d5 100644 --- a/content/resources/faq/tuning-postgresql.markdown +++ b/content/resources/faq/tuning-postgresql.markdown @@ -9,29 +9,29 @@ Depending on various factors your `postgresql.conf` may benefit from further tun Parameters commonly tuned: -* `max_connections` +- `max_connections` -* `shared_buffers` +- `shared_buffers` -* `effective_cache_size` +- `effective_cache_size` -* `maintenance_work_mem` +- `maintenance_work_mem` -* `checkpoint_completion_target` +- `checkpoint_completion_target` -* `wal_buffers` +- `wal_buffers` -* `default_statistics_target` +- `default_statistics_target` -* `random_page_cost` +- `random_page_cost` -* `effective_io_concurrency` +- `effective_io_concurrency` -* `work_mem` +- `work_mem` -* `min_wal_size` +- `min_wal_size` -* `max_wal_size` +- `max_wal_size` Tuning tools like [pgtune](https://github.com/kofemann/pgtune) and [pgconfigurator](https://www.cybertec-postgresql.com/en/products/pgconfigurator/) can be helpful in adjusting your settings. diff --git a/content/resources/faq/unable-to-log-in-mission-portal.markdown b/content/resources/faq/unable-to-log-in-mission-portal.markdown index f9d8b9546..1e265ae95 100644 --- a/content/resources/faq/unable-to-log-in-mission-portal.markdown +++ b/content/resources/faq/unable-to-log-in-mission-portal.markdown @@ -10,15 +10,15 @@ If your ssl certificate does not match the name used to access Mission Portal th Verify the name used to access mission portal resolves correctly: -* `/etc/hosts` contains a proper entry with the fqdn used to access Mission +- `/etc/hosts` contains a proper entry with the fqdn used to access Mission Portal listed in the second column. ``` 192.168.56.1 hub.cfengine.com hub ``` -* `hostname -f` returns the fqdn used to access Mission Portal. -* `hostname -s` returns the short hostname +- `hostname -f` returns the fqdn used to access Mission Portal. +- `hostname -s` returns the short hostname ## Mis-aligned oauth configuration diff --git a/content/resources/faq/what-did-cfengine-change.markdown b/content/resources/faq/what-did-cfengine-change.markdown index 63663b9e8..35bd37985 100644 --- a/content/resources/faq/what-did-cfengine-change.markdown +++ b/content/resources/faq/what-did-cfengine-change.markdown @@ -263,7 +263,7 @@ Reference: [query api examples][SQL query examples] ### promise_log.jsonl -**NOTE:*** These logs are purged upon collection by the hub. +**NOTE:\*** These logs are purged upon collection by the hub. Beginning with Enterprise 3.9.0 we began logging promise outcomes to a JSON format in `$(sys.statedir)/promise_log.jsonl` diff --git a/content/resources/faq/why-are-remote-agents-not-updating.markdown b/content/resources/faq/why-are-remote-agents-not-updating.markdown index faf5de27b..4c53e576e 100644 --- a/content/resources/faq/why-are-remote-agents-not-updating.markdown +++ b/content/resources/faq/why-are-remote-agents-not-updating.markdown @@ -24,12 +24,12 @@ update their policy when they notice that change. If the policy does not validate `$(sys.masterdir)/cf_promises_validated` is not updated, and remote clients will see no need to scan for updates. -* Check that the policy on in `$(sys.masterdir)` on the hub validates with +- Check that the policy on in `$(sys.masterdir)` on the hub validates with `cf-promises`. -* Check if `$(sys.inputdir)/cf_promises_validated` differs from the +- Check if `$(sys.inputdir)/cf_promises_validated` differs from the `$(sys.masterdir)/cf_promises_validated` on the policy server. -* Trigger a full policy scan with `cf-agent --no-lock --file update.cf --define - validated_updates_ready` +- Trigger a full policy scan with `cf-agent --no-lock --file update.cf --define +validated_updates_ready` **Note:** Dynamic inputs could mean different validation results on different hosts. Be conscious of different perspectives when validating policy. diff --git a/content/web-ui/_index.markdown b/content/web-ui/_index.markdown index 9a77faaf0..3cae3fae3 100644 --- a/content/web-ui/_index.markdown +++ b/content/web-ui/_index.markdown @@ -63,7 +63,7 @@ made by `cf-agent`. ### Event log -The Event Log records a time-line of *significant events*. +The Event Log records a time-line of _significant events_. Examples of significant events include: @@ -86,7 +86,7 @@ All Events can be searched and viewed from the Event Log page. Events Log page -- The Mission Portal RBAC for `View whole system events` is required to view the Event Log page. +- The Mission Portal RBAC for `View whole system events` is required to view the Event Log page. Mission Portal - Events View whole system events RBAC page @@ -176,11 +176,11 @@ From the profile, you can adjust timezone options. User Profile -* Time zone - * You can select any time zone from the searchable drop-down. -* Autodetect time zone change and ask for update - * If this option is selected Mission portal will ask you to update time zone when a difference is detected from your browser. - Time zone modal +- Time zone + - You can select any time zone from the searchable drop-down. +- Autodetect time zone change and ask for update + - If this option is selected Mission portal will ask you to update time zone when a difference is detected from your browser. + Time zone modal -* Always use system/browser time - * Mission portal will automatically change your profile timezone when a system/browser timezone is changed. +- Always use system/browser time + - Mission portal will automatically change your profile timezone when a system/browser timezone is changed. diff --git a/content/web-ui/alerts-and-notifications.markdown b/content/web-ui/alerts-and-notifications.markdown index cbe5a939f..a2a189380 100644 --- a/content/web-ui/alerts-and-notifications.markdown +++ b/content/web-ui/alerts-and-notifications.markdown @@ -6,54 +6,54 @@ sorting: 40 ## Create a new alert -* From the Dashboard, locate the rectangle with the dotted border. +- From the Dashboard, locate the rectangle with the dotted border. -* When the cursor is hovering over top, an **Add** button will appear. +- When the cursor is hovering over top, an **Add** button will appear. New Alerts -* Click the button to begin creating the alert. +- Click the button to begin creating the alert. New Alerts Name -* Add a unique name for the alert. +- Add a unique name for the alert. -* Each alert has a visual indication of its severity, represented by one of the following colors: - * **Low**: Yellow - * **Medium**: Orange - * **High**: Red +- Each alert has a visual indication of its severity, represented by one of the following colors: + - **Low**: Yellow + - **Medium**: Orange + - **High**: Red New Alerts Severity -* From the **Severity** dropdown box, select one of the three options available. +- From the **Severity** dropdown box, select one of the three options available. -* The **Select Condition** drop down box represents an inventory of existing conditional rules, as well as an option to create a new one +- The **Select Condition** drop down box represents an inventory of existing conditional rules, as well as an option to create a new one New Alerts Condition -* When selecting an existing conditional rule, the name of the condition will automatically populate the mandatory condition **Name** field. +- When selecting an existing conditional rule, the name of the condition will automatically populate the mandatory condition **Name** field. -* When creating a new condition the **Name** field must be filled in. +- When creating a new condition the **Name** field must be filled in. New Alerts Condition Type -* Each alert also has a **Condition type**: - * **Policy** conditions trigger alerts based on CFEngine policy compliance status. They can be set on bundles, promisees, and promises. If nothing is specified, they will trigger alerts for all policy. +- Each alert also has a **Condition type**: + - **Policy** conditions trigger alerts based on CFEngine policy compliance status. They can be set on bundles, promisees, and promises. If nothing is specified, they will trigger alerts for all policy. - * **Inventory** conditions trigger alerts for inventory attributes. These attributes correspond to the ones found in inventory reports. + - **Inventory** conditions trigger alerts for inventory attributes. These attributes correspond to the ones found in inventory reports. - * **Software Updates** conditions trigger alerts based on packages available for update in the repository. They can be set either for a specific version or trigger on the latest version available. If neither a package nor a version is specified, they will trigger alerts for any update. + - **Software Updates** conditions trigger alerts based on packages available for update in the repository. They can be set either for a specific version or trigger on the latest version available. If neither a package nor a version is specified, they will trigger alerts for any update. - * **Custom SQL** conditions trigger alerts based on an SQL query. The SQL query must returns at least one column - `hostkey`. + - **Custom SQL** conditions trigger alerts based on an SQL query. The SQL query must returns at least one column - `hostkey`. -* Alert conditions can be limited to a subset of hosts. +- Alert conditions can be limited to a subset of hosts. New Alerts Hosts -* Notifications of alerts may be sent by email or custom action scripts. +- Notifications of alerts may be sent by email or custom action scripts. New Alerts Notifications -* Check **Email notifications** box to activate the field for entering the email address to notify. +- Check **Email notifications** box to activate the field for entering the email address to notify. -* The **Remind me** dropdown box provides a selection of intervals to send reminder emails for triggered events. +- The **Remind me** dropdown box provides a selection of intervals to send reminder emails for triggered events. diff --git a/content/web-ui/custom-actions-for-alerts.markdown b/content/web-ui/custom-actions-for-alerts.markdown index 98102fefe..41a0342e4 100644 --- a/content/web-ui/custom-actions-for-alerts.markdown +++ b/content/web-ui/custom-actions-for-alerts.markdown @@ -19,27 +19,27 @@ Most of the keys are common for all alerts, but some additional keys are defined These keys are present for all alert types. -| Key | Description | -|-----------------------------|-------------------------------------------------------------------------------------------------------| -| ALERT_ID | Unique ID (number). | -| ALERT_NAME | Name, as defined in when creating the alert (string). | -| ALERT_SEVERITY | Severity, as selected when creating the alert (string). | -| ALERT_LAST_CHECK | Last time alert state was checked (Unix epoch timestamp). | -| ALERT_LAST_EVENT_TIME | Last time the alert created an event log entry (Unix epoch timestamp). | -| ALERT_LAST_STATUS_CHANGE | Last time alert changed from triggered to cleared or the other way around (Unix epoch timestamp). | -| ALERT_STATUS | Current status, either 'fail' (triggered) or 'success' (cleared). | -| ALERT_FAILED_HOST | Number of hosts currently triggered on (number). | -| ALERT_TOTAL_HOST | Number of hosts defined for (number). | -| ALERT_CONDITION_NAME | Condition name, as defined when creating the alert (string). | -| ALERT_CONDITION_DESCRIPTION | Condition description, as defined when creating the alert (string). | -| ALERT_CONDITION_TYPE | Type, as selected when creating the alert. Can be 'policy', 'inventory', or 'softwareupdate'. | +| Key | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------- | +| ALERT_ID | Unique ID (number). | +| ALERT_NAME | Name, as defined in when creating the alert (string). | +| ALERT_SEVERITY | Severity, as selected when creating the alert (string). | +| ALERT_LAST_CHECK | Last time alert state was checked (Unix epoch timestamp). | +| ALERT_LAST_EVENT_TIME | Last time the alert created an event log entry (Unix epoch timestamp). | +| ALERT_LAST_STATUS_CHANGE | Last time alert changed from triggered to cleared or the other way around (Unix epoch timestamp). | +| ALERT_STATUS | Current status, either 'fail' (triggered) or 'success' (cleared). | +| ALERT_FAILED_HOST | Number of hosts currently triggered on (number). | +| ALERT_TOTAL_HOST | Number of hosts defined for (number). | +| ALERT_CONDITION_NAME | Condition name, as defined when creating the alert (string). | +| ALERT_CONDITION_DESCRIPTION | Condition description, as defined when creating the alert (string). | +| ALERT_CONDITION_TYPE | Type, as selected when creating the alert. Can be 'policy', 'inventory', or 'softwareupdate'. | ### Policy keys In addition to the common keys, the following keys are present when ALERT_CONDITION_TYPE='policy'. -| Key | Description | -|---------------------------------------|------------------------------------------------------------------------------------------------------------------| +| Key | Description | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | ALERT_POLICY_CONDITION_FILTERBY | Policy object to filter by, as selected when creating the alert. Can be 'bundlename', 'promiser' or 'promisees'. | | ALERT_POLICY_CONDITION_FILTERITEMNAME | Name of the policy object to filter by, as defined when creating the alert (string). | | ALERT_POLICY_CONDITION_PROMISEHANDLE | Promise handle to filter by, as defined when creating the alert (string). | @@ -49,18 +49,18 @@ In addition to the common keys, the following keys are present when ALERT_CONDIT In addition to the common keys, the following keys are present when ALERT_CONDITION_TYPE='inventory'. -| Key | Description | -|--------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| ALERT_INVENTORY_CONDITION_FILTER_$(ATTRIBUTE_NAME) | The name of the attribute as selected when creating the alert is part of the key (expanded), while the value set when creating is the value (e.g. ALERT_INVENTORY_CONDITION_FILTER_ARCHITECTURE='x86_64'). | -| ALERT_INVENTORY_CONDITION_FILTER_$(ATTRIBUTE_NAME)_CONDITION | The name of the attribute as selected when creating the alert is part of the key (expanded), while the value is the comparison operator selected. Can be 'ILIKE' (matches), 'NOT ILIKE' (doesn't match), '=' (is), '!=' (is not), '<', '>'. | -| ... | There will be pairs of key=value for each attribute name defined in the alert. | +| Key | Description | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| ALERT*INVENTORY_CONDITION_FILTER*$(ATTRIBUTE_NAME) | The name of the attribute as selected when creating the alert is part of the key (expanded), while the value set when creating is the value (e.g. ALERT_INVENTORY_CONDITION_FILTER_ARCHITECTURE='x86_64'). | +| ALERT*INVENTORY_CONDITION_FILTER*$(ATTRIBUTE_NAME)\_CONDITION | The name of the attribute as selected when creating the alert is part of the key (expanded), while the value is the comparison operator selected. Can be 'ILIKE' (matches), 'NOT ILIKE' (doesn't match), '=' (is), '!=' (is not), '<', '>'. | +| ... | There will be pairs of key=value for each attribute name defined in the alert. | ### Software updates keys In addition to the common keys, the following keys are present when ALERT_CONDITION_TYPE='softwareupdate'. -| Key | Description | -|---------------------------------------------------|---------------------------------------------------------------------------------------------| +| Key | Description | +| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | ALERT_SOFTWARE_UPDATE_CONDITION_PATCHNAME | The name of the package, as defined when creating the alert, or empty if undefined (string). | | ALERT_SOFTWARE_UPDATE_CONDITION_PATCHARCHITECTURE | The architecture of the package, as defined when creating the alert, or empty if undefined (string). | diff --git a/content/web-ui/debugging-mission-portal.markdown b/content/web-ui/debugging-mission-portal.markdown index cd8866f4f..709074c99 100644 --- a/content/web-ui/debugging-mission-portal.markdown +++ b/content/web-ui/debugging-mission-portal.markdown @@ -38,6 +38,7 @@ sorting: 90 LD_LIBRARY_PATH=/var/cfengine/lib:$LD_LIBRARY_PATH /var/cfengine/httpd/bin/apachectl restart ``` -5. Watch the logs: -* `/var/cfengine/httpd/logs/error_log` -* `/var/cfengine/httpd/htdocs/application/logs/log-$(date +%Y-%m-%d).php` +5. Watch the logs: + +- `/var/cfengine/httpd/logs/error_log` +- `/var/cfengine/httpd/htdocs/application/logs/log-$(date +%Y-%m-%d).php` diff --git a/content/web-ui/enterprise-reporting/_index.markdown b/content/web-ui/enterprise-reporting/_index.markdown index 0b616be29..034d60085 100644 --- a/content/web-ui/enterprise-reporting/_index.markdown +++ b/content/web-ui/enterprise-reporting/_index.markdown @@ -24,22 +24,22 @@ meta tags matching [`metatags_include`][access#metatags_include] and do not have any meta tags matching [`metatags_exclude`][access#metatags_exclude] and does not have a handle matching [`promise_handle_exclude`][access#promise_handle_exclude]. `cf-hub` collects -*namespace* scoped (global) `classes` having any meta tags matching +_namespace_ scoped (global) `classes` having any meta tags matching [`metatags_include`][access#metatags_include] that do not have any meta tags matching [`metatags_exclude`][access#metatags_exclude]. Instead of modifying the list of regular expressions to control collection, we recommend that you leverage the defaults provided by the MPF (Masterfiles Policy -Framework). The MPF includes ```inventory``` and ```report``` in -[`metatags_include`][access#metatags_include], ```noreport``` in -[`metatags_exclude`][access#metatags_exclude] and ```noreport_.*``` in +Framework). The MPF includes `inventory` and `report` in +[`metatags_include`][access#metatags_include], `noreport` in +[`metatags_exclude`][access#metatags_exclude] and `noreport_.*` in [`promise_handle_exclude`][access#promise_handle_exclude]. If it's desirable for the classes and variables to be available in specialized inventory subsystem then it should be tagged with `inventory` and given an additional `attribute_name=` tag as described in the [custom inventory example][Custom inventory]. -```cf-hub``` collects information resulting from all other promise types (except +`cf-hub` collects information resulting from all other promise types (except `reports`, and `defaults` which cf-hub does not collect for). This can be further restricted by specifying [promise_handle_include][access#promise_handle_include] or @@ -56,11 +56,11 @@ collected into central reporting. Data that is too large to be reported will be truncated and a verbose level log message will be generated by cf-agent. Some noteable limitations are listed below. -* string variables are limited to 1024 bytes -* lists are limited to 1024 bytes of serialized data -* data variables are limited to 1024 bytes of serialized data -* meta tags limited to 1024 bytes of serailized output -* log messages are truncated to 400 bytes +- string variables are limited to 1024 bytes +- lists are limited to 1024 bytes of serialized data +- data variables are limited to 1024 bytes of serialized data +- meta tags limited to 1024 bytes of serailized output +- log messages are truncated to 400 bytes Please note that these limits may be lower in practice due to internal encoding. diff --git a/content/web-ui/enterprise-reporting/reporting-architecture.markdown b/content/web-ui/enterprise-reporting/reporting-architecture.markdown index 4f82231a1..fc85bd5a1 100644 --- a/content/web-ui/enterprise-reporting/reporting-architecture.markdown +++ b/content/web-ui/enterprise-reporting/reporting-architecture.markdown @@ -22,12 +22,12 @@ To collect reports from any host manually, run the following: /var/cfengine/bin/cf-hub -H ``` -* Add `-v` to run in verbose mode to diagnose connectivity issues and trace the data collected. +- Add `-v` to run in verbose mode to diagnose connectivity issues and trace the data collected. -* Delta (differential) reporting, the default mode, collects data that has changed since the -last collection. Rebase (full) reports collect everything. You can choose the full collection by -adding `-q rebase` (for backwards comapatibility, also available as -`-q full`). +- Delta (differential) reporting, the default mode, collects data that has changed since the + last collection. Rebase (full) reports collect everything. You can choose the full collection by + adding `-q rebase` (for backwards comapatibility, also available as + `-q full`). ## Apache diff --git a/content/web-ui/enterprise-reporting/reporting_ui.markdown b/content/web-ui/enterprise-reporting/reporting_ui.markdown index a6a4a03a1..5de638dd1 100644 --- a/content/web-ui/enterprise-reporting/reporting_ui.markdown +++ b/content/web-ui/enterprise-reporting/reporting_ui.markdown @@ -29,34 +29,34 @@ You can also filter on the type of promise: user defined, system defined, or all See also: -* [Reporting architecture][Reporting architecture] -* [SQL queries using the Enterprise API][SQL queries using the Enterprise API] +- [Reporting architecture][Reporting architecture] +- [SQL queries using the Enterprise API][SQL queries using the Enterprise API] ## Query builder Users not familiar with SQL syntax can easily create their own custom reports in this interface. Please note that query builder can be [extended with your custom data][Extending Query builder in Mission portal#How to add new table to query builder]. -* Tables - Select the data tables you want include in your report first. - * When more than one table is selected the Query builder opens modal window to select the ([join strategy between tables](https://www.postgresql.org/docs/current/tutorial-join.html)): - * Main table - the main data source, other tables will be connected to it. - * Extend main table (left join) - returns all records from the main table, and the matched records from the joined table. - * Include only common rows (inner join) - returns records from the main table that intersect the joined table. - Useful for filtering, in the case where you have custom views that have pre-filtered hosts. For example, web_servers - a custom view that contains hostkeys of hosts that are web servers. -* Fields - Define your table columns based on your selection above. -* Filters - Filter your results. Remember that unless you filter, you may be querying large data sets, so think about what you absolutely need in your report. -* Group - Group your results. May be expensive with large data sets. -* Sort - Sort your results. May be expensive with large data sets. -* Limit - Limit the number of entries in your report. This is a recommended practice for testing your query, and even in production it may be helpful if you don't need to see every entry. -* Show me the query - View and edit the SQL query directly. Please note, that editing the query directly here will invalidate your choices in the query builder interface, and changing your selections there will override your SQL query. +- Tables - Select the data tables you want include in your report first. + - When more than one table is selected the Query builder opens modal window to select the ([join strategy between tables](https://www.postgresql.org/docs/current/tutorial-join.html)): + - Main table - the main data source, other tables will be connected to it. + - Extend main table (left join) - returns all records from the main table, and the matched records from the joined table. + - Include only common rows (inner join) - returns records from the main table that intersect the joined table. + Useful for filtering, in the case where you have custom views that have pre-filtered hosts. For example, web_servers - a custom view that contains hostkeys of hosts that are web servers. +- Fields - Define your table columns based on your selection above. +- Filters - Filter your results. Remember that unless you filter, you may be querying large data sets, so think about what you absolutely need in your report. +- Group - Group your results. May be expensive with large data sets. +- Sort - Sort your results. May be expensive with large data sets. +- Limit - Limit the number of entries in your report. This is a recommended practice for testing your query, and even in production it may be helpful if you don't need to see every entry. +- Show me the query - View and edit the SQL query directly. Please note, that editing the query directly here will invalidate your choices in the query builder interface, and changing your selections there will override your SQL query. Report Builder ### Ensure the report collection is working -* The reporting bundle must be called from `promises.cf`. For example, -the following defines the attribute `Role` which is set to -`database_server`. You need to add it to the top-level -`bundlesequence` in `promises.cf` or in a bundle that it calls. +- The reporting bundle must be called from `promises.cf`. For example, + the following defines the attribute `Role` which is set to + `database_server`. You need to add it to the top-level + `bundlesequence` in `promises.cf` or in a bundle that it calls. ```cf3 {file="promises.cf"} bundle agent myreport @@ -68,19 +68,19 @@ bundle agent myreport } ``` -* note the [`meta`][Promise types#meta] tag `inventory` +- note the [`meta`][Promise types#meta] tag `inventory` -* The hub must be able to collect the reports from the client. TCP -port 5308 must be open and, because 3.6 uses TLS, should not be -proxied or otherwise intercepted. Note that bootstrapping and other -standalone client operations go from the client to the server, so the -ability to bootstrap and copy policies from the server doesn't -necessarily mean the reverse connection will work. +- The hub must be able to collect the reports from the client. TCP + port 5308 must be open and, because 3.6 uses TLS, should not be + proxied or otherwise intercepted. Note that bootstrapping and other + standalone client operations go from the client to the server, so the + ability to bootstrap and copy policies from the server doesn't + necessarily mean the reverse connection will work. -* Ensure that variables and classes tagged as `inventory` or `report` -are not filtered by `controls/cf_serverd.cf` in your infrastructure. -The standard configuration from the stock CFEngine packages allows -them and should work. +- Ensure that variables and classes tagged as `inventory` or `report` + are not filtered by `controls/cf_serverd.cf` in your infrastructure. + The standard configuration from the stock CFEngine packages allows + them and should work. **Note:** The CFEngine report collection model accounts for long periods of time when the hub is unable to collect data from remote agents. This model @@ -97,30 +97,30 @@ performance until it has been able to collect from all hosts. ## Define a new single table report -1. In *Mission Portal* select the *Report* application icon on the left hand side of the screen. -2. This will bring you to the *Report builder* screen. -3. The default for what hosts to report on is *All hosts*. The hosts can be filtered under the *Filters* section at the top of the page. -4. For this tutorial leave it as *All hosts*. +1. In _Mission Portal_ select the _Report_ application icon on the left hand side of the screen. +2. This will bring you to the _Report builder_ screen. +3. The default for what hosts to report on is _All hosts_. The hosts can be filtered under the _Filters_ section at the top of the page. +4. For this tutorial leave it as _All hosts_. 5. Set which tables' data we want reports for. -6. For this tutorial select *Hosts*. -7. Select the columns from the *Hosts* table for the report. -8. For this tutorial click the *Select all* link below the column lables. -9. Leave *Filters*, *Sort*, and *Limit* at the default settings. -10. Click the orange *Run* button in the bottom right hand corner. +6. For this tutorial select _Hosts_. +7. Select the columns from the _Hosts_ table for the report. +8. For this tutorial click the _Select all_ link below the column lables. +9. Leave _Filters_, _Sort_, and _Limit_ at the default settings. +10. Click the orange _Run_ button in the bottom right hand corner. ## Check report results 1. The report generated will show each of the selected columns across the report table's header row. -2. In this tutorial the columns being reported back should be: *Host key*, *Last report time*, *Host name*, *IP address*, *First report-time*. +2. In this tutorial the columns being reported back should be: _Host key_, _Last report time_, _Host name_, _IP address_, _First report-time_. 3. Each row will contain the information for an individual data record, in this case one row for each host. -4. Some of the cells in the report may provide links to drill down into more detailed information (e.g. *Host name* will provide a link to a *Host information* page). +4. Some of the cells in the report may provide links to drill down into more detailed information (e.g. _Host name_ will provide a link to a _Host information_ page). 5. It is possible to also export the report to a file. -6. Click the orange *Export* button. -7. You will then see a *Report Download* dialog. -8. *Report type* can be either *csv* or *pdf format*. +6. Click the orange _Export_ button. +7. You will then see a _Report Download_ dialog. +8. _Report type_ can be either _csv_ or _pdf format_. 9. Leave other fields at the default values. -10. If the server's mail configuration is working properly, it is possible to email the report by checking the *Send in email* box. -11. Click *OK* to download or email the *csv* or *pdf* version of the report. +10. If the server's mail configuration is working properly, it is possible to email the report by checking the _Send in email_ box. +11. Click _OK_ to download or email the _csv_ or _pdf_ version of the report. 12. Once the report is generated it will be available for download or will be emailed. ## Inventory management @@ -131,7 +131,7 @@ The main Inventory screen shows the current set of hosts, together with relevant Inventory management -To begin filtering, one would first select the *Filters* drop down, and then select an attribute to filter on (e.g. OS type = linux) +To begin filtering, one would first select the _Filters_ drop down, and then select an attribute to filter on (e.g. OS type = linux) Inventory management diff --git a/content/web-ui/enterprise-reporting/sql-queries-enterprise-api.markdown b/content/web-ui/enterprise-reporting/sql-queries-enterprise-api.markdown index 3b1574be3..dd3cf45f9 100644 --- a/content/web-ui/enterprise-reporting/sql-queries-enterprise-api.markdown +++ b/content/web-ui/enterprise-reporting/sql-queries-enterprise-api.markdown @@ -12,12 +12,12 @@ the Enterprise reporting API. Through the API, you can run CFEngine Enterprise reports with SQL queries. The API can create the following report queries: -- Synchronous query: Issue a query and wait for the table to - be sent back with the response. -- Asynchronous query: A query is issued and an immediate response with an ID is sent - so that you can check the query later to download the report. -- Subscribed query: Specify a query to be run on a schedule - and have the result emailed to someone. +- Synchronous query: Issue a query and wait for the table to + be sent back with the response. +- Asynchronous query: A query is issued and an immediate response with an ID is sent + so that you can check the query later to download the report. +- Subscribed query: Specify a query to be run on a schedule + and have the result emailed to someone. ### Synchronous queries diff --git a/content/web-ui/federated-reporting.markdown b/content/web-ui/federated-reporting.markdown index 416f12702..d42be00b1 100644 --- a/content/web-ui/federated-reporting.markdown +++ b/content/web-ui/federated-reporting.markdown @@ -53,10 +53,10 @@ The Superhub aggregates all the data from all the Feeders connected to it which is a periodically running resource intensive task. The key factors contributing to HW requirements for the Superhub are: -* The refresh interval at which data is pulled from the Feeders and imported on +- The refresh interval at which data is pulled from the Feeders and imported on the Superhub. The default is 20 minutes and it can be changed in the policy. -* The amount of data gathered on the Feeders from the reports sent by the +- The amount of data gathered on the Feeders from the reports sent by the hosts bootstrapped to them. The current implementation of Federated reporting is not aggregating monitoring @@ -77,18 +77,18 @@ would degrade the freshness of the data available on the Superhub. The recommended HW configuration for a Superhub with the default configuration and 5000 hosts per connected Feeder is: - * 16 GiB of RAM or more, +- 16 GiB of RAM or more, - * 1 logical CPU per connected Feeder or more, +- 1 logical CPU per connected Feeder or more, - * 5 MiB of disk space per host or more, +- 5 MiB of disk space per host or more, - * 1000 IOPS storage or faster, +- 1000 IOPS storage or faster, - * 100 Mib/s network bandwidth per connected Feeder, +- 100 Mib/s network bandwidth per connected Feeder, - * 135 KiB of network data transfer per host per one pull of the data from - Feeders. +- 135 KiB of network data transfer per host per one pull of the data from + Feeders. The Federated reporting process is logging information to the system log and so timestamps from the log messages can be used to determine how long each round of @@ -177,6 +177,7 @@ In the first case you will likely want to remove entries for hosts which are not There are two options available for handling these situations depending on your environment: Distributed Cleanup or Handle Duplicate Hostkeys. ### Distributed cleanup + This is the most thorough, performant and automated option. This utility is a python script which runs on the superhub, searches for the most recent contact for each host, then communicates with the appropriate feeders to delete stale hosts. @@ -189,13 +190,13 @@ A few pre-requisites must be handled before enabling this utility: On Debian/Ubuntu: -``` command +```command apt install -qy python3 python3-urllib3 ``` On RedHat/CentOS versions 7 and above: -``` command +```command yum install -qy python3 python3-urllib3 ``` @@ -209,6 +210,7 @@ After those steps, ensure `cfengine_mp_fr_enable_distributed_cleanup` is present "classes": { "cfengine_mp_fr_enable_distributed_cleanup": ["any::"] } } ``` + (Note that this augment should be in addition to any others that you need such as `cfengine_mp_fr_dependencies_auto_install`) Let the policy run a few times on superhub and feeders. @@ -216,6 +218,7 @@ This will distribute the needed certificates from feeders to superhub so that th When run manually for the first time the utility will create a limited privileges user to view and delete hosts on the feeders. You will need to enter the following information at the prompts when running the utility manually: + - admin password for the superhub - email address for the fr_distributed_cleanup limited privileges user - admin password for each feeder @@ -238,6 +241,7 @@ The passwords are only kept for the duration of the script execution and are not The policy will now run the distributed cleanup utility every agent run and cleanup any hosts which are stale on feeders leaving only the most recently contacts host for each unique hostkey. ### Handle duplicate hostkeys + The other option removes duplicates during each import cycle. An augment is available to enable moving duplicated host data to a `dup` schema for analysis. The host data which has the most recent `hosts.lastreporttimestamp` will be kept in the `public` schema and all other data will be moved to the `dup` domain (schema). @@ -251,6 +255,7 @@ If enabled it is performed on every import cycle. ``` This class only has an effect on the superhub host. + ## Troubleshooting Please refer to `/var/cfengine/output`, `/var/log/postgresql.log` and @@ -286,7 +291,7 @@ In these examples we use the `admin` account because the Admin Role which this u ### Stop cf-execd on the superhub and feeder We don't want periodic agent runs to get in our ways so let's disable -*cf-execd*. +_cf-execd_. ```console $ cf-remote sudo -H $CLOUD_USER$SUPERHUB,$CLOUD_USER$FEEDER "systemctl stop cf-execd" @@ -588,29 +593,29 @@ There are two ways to change the `target_state` of a feeder. 1. Prepare a JSON data file: - ```console - $ cat < target-state-off.json - { - "target_state": "off" - } - EOF - ``` +```console +$ cat < target-state-off.json +{ + "target_state": "off" +} +EOF +``` 2. Change the state of the feeder: - ```command - curl -k -i -s -X PUT -u admin:$PASSWORD https://$FEEDER/api/fr/hub-state -d @target-state-off.json --header "Content-Type: application/json" - ``` +```command +curl -k -i -s -X PUT -u admin:$PASSWORD https://$FEEDER/api/fr/hub-state -d @target-state-off.json --header "Content-Type: application/json" +``` 3. **Save the federation config:** - ```command - curl -k -i -s -X POST -u admin:$PASSWORD https://$FEEDER/api/fr/federation-config - ``` +```command +curl -k -i -s -X POST -u admin:$PASSWORD https://$FEEDER/api/fr/federation-config +``` ### Uninstall without API -Edit ```/opt/cfengine/federation/cfapache/federation-config.json``` on the feeder +Edit `/opt/cfengine/federation/cfapache/federation-config.json` on the feeder you wish to disable and change the top-level `target_state` property value to `off`. ```json @@ -634,110 +639,111 @@ you wish to disable and change the top-level `target_state` property value to `o At this time it is not possible to remove a connected hub in the Mission Portal Hub management app. -* List all feeders to find the id value. Use of ```jq``` is optional for pretty printing the JSON. - - (Set approprivate values in your shell for `PASSWORD` and `SUPERHUB`) - ```command - curl -k -s -X GET -u admin:$PASSWORD https://$SUPERHUB/api/fr/remote-hub | jq '.' - ``` - - ```json {skip} - { - "id": 1, - "hostkey": "SHA=cd4be31f20f0c7d019a5d3bfe368415f2d34fec8af26ee28c4c123c6a0af49a2", - "api_url": "https://100.90.80.70", - "ui_name": "feeder1", - "role": "feeder", - "target_state": "on", - "transport": { - "mode": "pull_over_rsync", - "ssh_user": "cftransport", - "ssh_host": "172.32.1.20", - "ssh_pubkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVGoBB3zLKfVTzDNum/JWlmNJrSuDGrhTW1ZGtZEKjxFViFr4j0F8s6gIr5KOMcWtd91XvW6klpCPqKH3lfY767AI/RQa8JgVXgtvUG8rkD+gJ/wzGJm+VoGpxxs9dyBgSOtkaOSIDc574Om8dBR8enRcgxo1cNpvDVLVYKx9IzqhBwqp1gzEtGoIi+CDoGmoj1BT9XTlCRvGXYmSSBrgLARVO2mh5iqhP0XRVCp9Ki6OB9vMcs9rxIgQaPt8tVCt7/FK03IXrWPUsJC4M/kXiaKgHlE96H0CEvYl7GczaIU2NN5AHXZlviL79Zb8kOcUzsMdKv40G9YVa7/kyDOUX root@ip-172-32-1-20", - "ssh_fingerprint": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBF18li5PyCyVy27+Lv09HDRxhyEnlL+zK++WaLc78W+Gji5i2VSRDg/jVV0xU2ZUmkohULZ66OmI5/sCOOIa3XU=\nssh-ed25519" - }, - "statistics": [] - } - { - "id": 2, - "hostkey": "SHA=30b6bb15fb94c9b7e386521bbe566934d266db2f6f63cd85f5e6fc406d11110b", - "api_url": "https://100.90.80.60", - "ui_name": "feeder2", - "role": "feeder", - "target_state": "on", - "transport": { - "mode": "pull_over_rsync", - "ssh_user": "cftransport", - "ssh_host": "172.32.1.21", - "ssh_pubkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDin59ffTXhtQxahrYkqNi3x36XIO08GnOvvVe3s+DmuT3kBn8Lh4P30kOVONSGKcfNZLnWVPrk2qqNWuEi6xg861G1kXqce02c26BW+4L/tnz86/kmTBGc2vb6d1NpEKA/1bg6bMf1da+EInxuMsS+yOWCe+s6DJ00bg6iCnmlLYtzAkMXmXK5QgVG6AImJXqG1Px5DlsRcKto00J8WJswfTpQXbZbuog4J6Ltm/J4DQW1/x7pEJby/r+/lKPJWp19t0gaGXfsxwHEPFK6YC8zmFzkBeqiVpAizhs7G8mZDgAAhMyY8d2eYIp+hDIFpfQA3aHHr0L7emsFeDa/rExt root@ip-172-32-1-21", - "ssh_fingerprint": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7HE4qJfTLP9j02jZnkpTpUMCBiFzmAemgvIPcJjWJVNcawh1hpGSsWjw9EM1kwn7J6fWrjEkY8lTi2pNTnobL9qt+oQvwFqUvs5EZ8gAVIAyDjKE8GLckZRt8VGxLWMtOlBKaAmPBn0eFP6ToPqnPygJiiM05vKtxPui1xuCTrW+rXShtolUJLwwGH2APcDqjKAdZceQK4nybJzk4J1P77sJc+9IlHJCTpfj8AQEbh/Z3cHtNKauaz1mhDn5YT/QWwzKavGlqFSlSDwLXT2go6P6FoSaVYTV45V9l7q6ahEy3zEe7+7psMFVucS512qYFEKn5FoSIVQLgT3I8MfI1\necdsa-sha2-nistp256" - }, - "statistics": [] - } - ``` - -* Determine the id from the "id" property value and delete the remote hub with the API. In this case -we use the number "1". - - ```console - root@superhub: ~# REMOTE_HUB_ID=1 - root@superhub: ~# curl -k -s -X DELETE -u admin:$PASSWORD https://$SUPERHUB/api/fr/remote-hub/$REMOTE_HUB_ID - ``` - -* Remove the feeder from `/opt/cfengine/federation/cfapache/federation-config.json`. Replace "id-1" below with the appropriate id from the previous steps. - - ```command - contents=$(jq 'del(.remote_hubs ."id-1")' /opt/cfengine/federation/cfapache/federation-config.json) && echo "${contents}" > /opt/cfengine/federation/cfapache/federation-config.json - ``` - -* Remove items associated with this feeder in the `cfdb` database. - - Determine the cfdb-specific `hub_id`. - - ```command - /var/cfengine/bin/psql cfdb -c "select * from __hubs" - ``` - - Typical output would be like the following. - - ``` - hub_id | hostkey | last_import_ts - --------+----------------------------------------------------------------------+---------------- - 0 | SHA=50d370f41c81b3e119506befecc5deaa63c0f1d9039f674c68f9253a07f7ad84 | - 1 | SHA=bfd6f580f9d19cb190139452f068f38f843bf9227ca3515f7adfecfa39f68728 | - (2 rows) - ``` - - `hub_id` of `0` is the superhub. The others are the feeders. - In this case, it happens that the `hub_id` is also "1" so we will use that in the following queries. - -* Execute the following commands to remove the namespace for that feeder as well as the entry in the `__hubs` table. - - ```console - root@superhub: ~# /var/cfengine/bin/psql cfdb -c 'drop schema "hub_1" cascade;' - root@superhub: ~# /var/cfengine/bin/psql cfdb -c "delete from __hubs where hub_id = 1" - ``` - -* On the feeder, replace `/opt/cfengine/federation/cfapache/federation-config.json` with the following content. +- List all feeders to find the id value. Use of `jq` is optional for pretty printing the JSON. + + (Set approprivate values in your shell for `PASSWORD` and `SUPERHUB`) + + ```command + curl -k -s -X GET -u admin:$PASSWORD https://$SUPERHUB/api/fr/remote-hub | jq '.' + ``` + + ```json {skip} + { + "id": 1, + "hostkey": "SHA=cd4be31f20f0c7d019a5d3bfe368415f2d34fec8af26ee28c4c123c6a0af49a2", + "api_url": "https://100.90.80.70", + "ui_name": "feeder1", + "role": "feeder", + "target_state": "on", + "transport": { + "mode": "pull_over_rsync", + "ssh_user": "cftransport", + "ssh_host": "172.32.1.20", + "ssh_pubkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDVGoBB3zLKfVTzDNum/JWlmNJrSuDGrhTW1ZGtZEKjxFViFr4j0F8s6gIr5KOMcWtd91XvW6klpCPqKH3lfY767AI/RQa8JgVXgtvUG8rkD+gJ/wzGJm+VoGpxxs9dyBgSOtkaOSIDc574Om8dBR8enRcgxo1cNpvDVLVYKx9IzqhBwqp1gzEtGoIi+CDoGmoj1BT9XTlCRvGXYmSSBrgLARVO2mh5iqhP0XRVCp9Ki6OB9vMcs9rxIgQaPt8tVCt7/FK03IXrWPUsJC4M/kXiaKgHlE96H0CEvYl7GczaIU2NN5AHXZlviL79Zb8kOcUzsMdKv40G9YVa7/kyDOUX root@ip-172-32-1-20", + "ssh_fingerprint": "ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBF18li5PyCyVy27+Lv09HDRxhyEnlL+zK++WaLc78W+Gji5i2VSRDg/jVV0xU2ZUmkohULZ66OmI5/sCOOIa3XU=\nssh-ed25519" + }, + "statistics": [] + } + { + "id": 2, + "hostkey": "SHA=30b6bb15fb94c9b7e386521bbe566934d266db2f6f63cd85f5e6fc406d11110b", + "api_url": "https://100.90.80.60", + "ui_name": "feeder2", + "role": "feeder", + "target_state": "on", + "transport": { + "mode": "pull_over_rsync", + "ssh_user": "cftransport", + "ssh_host": "172.32.1.21", + "ssh_pubkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDin59ffTXhtQxahrYkqNi3x36XIO08GnOvvVe3s+DmuT3kBn8Lh4P30kOVONSGKcfNZLnWVPrk2qqNWuEi6xg861G1kXqce02c26BW+4L/tnz86/kmTBGc2vb6d1NpEKA/1bg6bMf1da+EInxuMsS+yOWCe+s6DJ00bg6iCnmlLYtzAkMXmXK5QgVG6AImJXqG1Px5DlsRcKto00J8WJswfTpQXbZbuog4J6Ltm/J4DQW1/x7pEJby/r+/lKPJWp19t0gaGXfsxwHEPFK6YC8zmFzkBeqiVpAizhs7G8mZDgAAhMyY8d2eYIp+hDIFpfQA3aHHr0L7emsFeDa/rExt root@ip-172-32-1-21", + "ssh_fingerprint": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC7HE4qJfTLP9j02jZnkpTpUMCBiFzmAemgvIPcJjWJVNcawh1hpGSsWjw9EM1kwn7J6fWrjEkY8lTi2pNTnobL9qt+oQvwFqUvs5EZ8gAVIAyDjKE8GLckZRt8VGxLWMtOlBKaAmPBn0eFP6ToPqnPygJiiM05vKtxPui1xuCTrW+rXShtolUJLwwGH2APcDqjKAdZceQK4nybJzk4J1P77sJc+9IlHJCTpfj8AQEbh/Z3cHtNKauaz1mhDn5YT/QWwzKavGlqFSlSDwLXT2go6P6FoSaVYTV45V9l7q6ahEy3zEe7+7psMFVucS512qYFEKn5FoSIVQLgT3I8MfI1\necdsa-sha2-nistp256" + }, + "statistics": [] + } + ``` + +- Determine the id from the "id" property value and delete the remote hub with the API. In this case + we use the number "1". + + ```console + root@superhub: ~# REMOTE_HUB_ID=1 + root@superhub: ~# curl -k -s -X DELETE -u admin:$PASSWORD https://$SUPERHUB/api/fr/remote-hub/$REMOTE_HUB_ID + ``` + +- Remove the feeder from `/opt/cfengine/federation/cfapache/federation-config.json`. Replace "id-1" below with the appropriate id from the previous steps. + + ```command + contents=$(jq 'del(.remote_hubs ."id-1")' /opt/cfengine/federation/cfapache/federation-config.json) && echo "${contents}" > /opt/cfengine/federation/cfapache/federation-config.json + ``` + +- Remove items associated with this feeder in the `cfdb` database. + + Determine the cfdb-specific `hub_id`. + + ```command + /var/cfengine/bin/psql cfdb -c "select * from __hubs" + ``` + + Typical output would be like the following. + + ``` + hub_id | hostkey | last_import_ts + --------+----------------------------------------------------------------------+---------------- + 0 | SHA=50d370f41c81b3e119506befecc5deaa63c0f1d9039f674c68f9253a07f7ad84 | + 1 | SHA=bfd6f580f9d19cb190139452f068f38f843bf9227ca3515f7adfecfa39f68728 | + (2 rows) + ``` + + `hub_id` of `0` is the superhub. The others are the feeders. + In this case, it happens that the `hub_id` is also "1" so we will use that in the following queries. + +- Execute the following commands to remove the namespace for that feeder as well as the entry in the `__hubs` table. + + ```console + root@superhub: ~# /var/cfengine/bin/psql cfdb -c 'drop schema "hub_1" cascade;' + root@superhub: ~# /var/cfengine/bin/psql cfdb -c "delete from __hubs where hub_id = 1" + ``` + +- On the feeder, replace `/opt/cfengine/federation/cfapache/federation-config.json` with the following content. If you wish to re-add this feeder to a superhub, change "target_state" from "off" to "on". Remember to trigger or wait for an agent run for the change from off to on to take effect. - ```json {skip TODO} - { - "hostname": null, - "role": "feeder", - "target_state": "off", - "remote_hubs": { } - } - ``` + ```json {skip TODO} + { + "hostname": null, + "role": "feeder", + "target_state": "off", + "remote_hubs": {} + } + ``` -* On 3.15.x and greater feeders, also run the following commands to truncate two tables: +- On 3.15.x and greater feeders, also run the following commands to truncate two tables: - ```console - root@feeder: ~# /var/cfengine/bin/psql cfsettings -c 'TRUNCATE remote_hubs' - root@feeder: ~# /var/cfengine/bin/psql cfsettings -c 'TRUNCATE federated_reporting_settings' - ``` + ```console + root@feeder: ~# /var/cfengine/bin/psql cfsettings -c 'TRUNCATE remote_hubs' + root@feeder: ~# /var/cfengine/bin/psql cfsettings -c 'TRUNCATE federated_reporting_settings' + ``` ## Superhub upgrade @@ -754,66 +760,67 @@ you may use the [Import & export API] or Mission Portal Settings UI to export an Follow this procedure: -* Download the new version from the [Enterprise Downloads Page][enterprise software download page] -* Export any items from Mission Portal you wish to migrate -* Stop all CFEngine services on the superhub +- Download the new version from the [Enterprise Downloads Page][enterprise software download page] +- Export any items from Mission Portal you wish to migrate +- Stop all CFEngine services on the superhub - ```command - systemctl stop cfengine3 - ``` + ```command + systemctl stop cfengine3 + ``` -* Uninstall CFEngine hub +- Uninstall CFEngine hub - ```command - rpm -e cfengine-nova-hub - ``` + ```command + rpm -e cfengine-nova-hub + ``` - or + or - ```command - apt-get remove cfengine-nova-hub - ``` + ```command + apt-get remove cfengine-nova-hub + ``` -* Cleanup directories +- Cleanup directories - ```command - rm -rf /var/cfengine /opt/cfengine - ``` -* Install new version of cfengine -* Confirm succesful installation + ```command + rm -rf /var/cfengine /opt/cfengine + ``` - ```command - grep -i err /var/log/CFEngineInstall.log - ``` +- Install new version of cfengine +- Confirm succesful installation -* Bootstrap the superhub to itself + ```command + grep -i err /var/log/CFEngineInstall.log + ``` - ```command - cf-agent --bootstrap - ``` +- Bootstrap the superhub to itself -* Reconfigure all feeders (3.15 series and newer, skip for 3.12 series feeder hubs) - * edit `/opt/cfengine/federation/cfapache/federation-config.json` to remove all entries in the `remote_hubs` property. - similar to the following: + ```command + cf-agent --bootstrap + ``` - ```json {skip TODO} - { - "hostname": null, - "role": "feeder", - "target_state": "on", - "remote_hubs": { } - } - ``` +- Reconfigure all feeders (3.15 series and newer, skip for 3.12 series feeder hubs) + - edit `/opt/cfengine/federation/cfapache/federation-config.json` to remove all entries in the `remote_hubs` property. + similar to the following: - * On 3.15.x and greater feeders, also truncate the `remote_hubs` table: + ```json {skip TODO} + { + "hostname": null, + "role": "feeder", + "target_state": "on", + "remote_hubs": {} + } + ``` - ```command - /var/cfengine/bin/psql cfsettings -c 'TRUNCATE remote_hubs' - ``` -* Reinstall and configure the superhub as described in [Installation][Federated reporting#Installation] -* Import any saved information into Mission Portal via the [Import & export API] or Mission Portal Settings UI -* Wait 20 minutes for federated reporting to be updated from feeders to superhub + - On 3.15.x and greater feeders, also truncate the `remote_hubs` table: - or + ```command + /var/cfengine/bin/psql cfsettings -c 'TRUNCATE remote_hubs' + ``` - * run `cf-agent -KI` on each feeder, and then `cf-agent -KI` on the superhub to manually force a Federated reporting collection cycle. +- Reinstall and configure the superhub as described in [Installation][Federated reporting#Installation] +- Import any saved information into Mission Portal via the [Import & export API] or Mission Portal Settings UI +- Wait 20 minutes for federated reporting to be updated from feeders to superhub + + or + - run `cf-agent -KI` on each feeder, and then `cf-agent -KI` on the superhub to manually force a Federated reporting collection cycle. diff --git a/content/web-ui/health.markdown b/content/web-ui/health.markdown index 6b6914ad3..8d6782bf3 100644 --- a/content/web-ui/health.markdown +++ b/content/web-ui/health.markdown @@ -8,12 +8,12 @@ sorting: 20 You can get quick access to the health of hosts, including direct links to reports, from the Health drop down at the top of every Enterprise UI screen. Hosts are listed as unhealthy if: -* Missing reporting data : Host has connected to hub (to get policy), but reports have never been collected from it. -* Unreachable hosts : Reports from host has been collected in the past, but not recently (as defined by "Unreachable host threshold"). -* Outdated reporting data : The host is communicating correctly and sending its reports, but the data is outdated (there are no recent reports), indicating that there hasn't been any policy runs recently (performed by the cf-agent binary). There is no data to prove that your policy, describing your desired state, is being successfully enforced. -* Policy errors : Reports have recently been collected and cf-agent has completed a run with an error. -* Duplicate IDs : CFEngine hosts are identified by the CFEngine key they use. If two or more hosts use the same key the reports will be very unreliable. This is detected by exchanging randomized cookies(tokens) during report collections. If a client sends a mismatching cookie (compared to last collection), it indicates that multiple hosts are using the same ID. -* Duplicate hostnames: multiple host identities reporting the same host identifier (by default hostname derived from `default:sys.fqhost` variable but changeable in Settings -> Host identifier) +- Missing reporting data : Host has connected to hub (to get policy), but reports have never been collected from it. +- Unreachable hosts : Reports from host has been collected in the past, but not recently (as defined by "Unreachable host threshold"). +- Outdated reporting data : The host is communicating correctly and sending its reports, but the data is outdated (there are no recent reports), indicating that there hasn't been any policy runs recently (performed by the cf-agent binary). There is no data to prove that your policy, describing your desired state, is being successfully enforced. +- Policy errors : Reports have recently been collected and cf-agent has completed a run with an error. +- Duplicate IDs : CFEngine hosts are identified by the CFEngine key they use. If two or more hosts use the same key the reports will be very unreliable. This is detected by exchanging randomized cookies(tokens) during report collections. If a client sends a mismatching cookie (compared to last collection), it indicates that multiple hosts are using the same ID. +- Duplicate hostnames: multiple host identities reporting the same host identifier (by default hostname derived from `default:sys.fqhost` variable but changeable in Settings -> Host identifier) These categories are non-overlapping, meaning a host will only appear in one category at at time even if conditions satisfying multiple categories might be present. This makes reports simpler to read, and makes it easier to detect and fix the root cause of the issue. As one issue is resolved the host might then move to another category. Regardless of the situation, the data from the host will be from the latest report collection, representing the most recent known state of the host. diff --git a/content/web-ui/hosts.markdown b/content/web-ui/hosts.markdown index a20e10a48..87ca270b1 100644 --- a/content/web-ui/hosts.markdown +++ b/content/web-ui/hosts.markdown @@ -8,8 +8,8 @@ The Hosts app provides a customizable global overview of _promise_ compliance. A Each host is in one of two groups: out of compliance or fully compliant. -* A host is considered out of compliance if less than 100% of its promises were kept. -* A host is considered fully compliant if 100% of its promises were kept. +- A host is considered out of compliance if less than 100% of its promises were kept. +- A host is considered fully compliant if 100% of its promises were kept. Hosts app overview @@ -31,10 +31,10 @@ Take action on a host. Host action buttons -* Run agent :: Request an unscheduled policy run -* Collect reports :: Request report collection -* Get URL :: Get the URL to the specific hosts info page -* Delete host :: Delete the host +- Run agent :: Request an unscheduled policy run +- Collect reports :: Request report collection +- Get URL :: Get the URL to the specific hosts info page +- Delete host :: Delete the host ### Host specific data diff --git a/content/web-ui/hub_administration/backup-and-restore.markdown b/content/web-ui/hub_administration/backup-and-restore.markdown index b6c528a1e..ea6ec22d3 100644 --- a/content/web-ui/hub_administration/backup-and-restore.markdown +++ b/content/web-ui/hub_administration/backup-and-restore.markdown @@ -52,8 +52,8 @@ pg_restore -Fc cfdb.bak ### Mission Portal - `cfmp` and `cfsettings` store Mission Portals configuration information for - example shared dashboards. +`cfmp` and `cfsettings` store Mission Portals configuration information for +example shared dashboards. **Backup:** diff --git a/content/web-ui/hub_administration/decommissioning-hosts.markdown b/content/web-ui/hub_administration/decommissioning-hosts.markdown index 34cbd2485..e2ec3f156 100644 --- a/content/web-ui/hub_administration/decommissioning-hosts.markdown +++ b/content/web-ui/hub_administration/decommissioning-hosts.markdown @@ -7,8 +7,8 @@ sorting: 30 Once a host is shut off, or CFEngine is uninstalled, you should remove it from Mission Portal. This has 2 benefits: -* Report collection will no longer count it as consuming a license. -* You won't see its data or get alerts for it in Mission Portal. +- Report collection will no longer count it as consuming a license. +- You won't see its data or get alerts for it in Mission Portal. **Removing a host from the hub / Mission Portal does not uninstall or stop CFEngine on that host.** Before removing hosts, please ensure that they are either completely gone (VM destroyed) or definitely not running CFEngine. @@ -16,19 +16,19 @@ If the host is still running CFEngine, or there is another host running with the Hosts can be removed via API or UI, the outcome is the same: -* The host is deleted from all tables/views in PostgreSQL, including `hosts`, `inventory`, etc. - * There may still be references to the host in reporting data from other hosts. -* The host is deleted from `cf_lastseen.lmdb` the database used for discovering hosts for report collection. -* The hosts cryptographic key is removed from the `ppkeys` directory. +- The host is deleted from all tables/views in PostgreSQL, including `hosts`, `inventory`, etc. + - There may still be references to the host in reporting data from other hosts. +- The host is deleted from `cf_lastseen.lmdb` the database used for discovering hosts for report collection. +- The hosts cryptographic key is removed from the `ppkeys` directory. Please note that: -* Users with admin role can delete hosts without reporting data (which don't show up in Mission Portal). -* Host deletion is a scheduled operation, the `cf-hub` process will pick up the deletion request later. - * This is because of security concerns, the Apache user does not have direct access to the necessary files. - * It may take a few minutes before the host disappears from all the places listed above. -* For these reasons the HTTP response code is normally `202 Accepted`. - * At the time of the API response, it is not possible to know whether the host exists in all the places mentioned above. +- Users with admin role can delete hosts without reporting data (which don't show up in Mission Portal). +- Host deletion is a scheduled operation, the `cf-hub` process will pick up the deletion request later. + - This is because of security concerns, the Apache user does not have direct access to the necessary files. + - It may take a few minutes before the host disappears from all the places listed above. +- For these reasons the HTTP response code is normally `202 Accepted`. + - At the time of the API response, it is not possible to know whether the host exists in all the places mentioned above. ## Host removal through Mission Portal UI diff --git a/content/web-ui/hub_administration/extending-mission-portal.markdown b/content/web-ui/hub_administration/extending-mission-portal.markdown index 30cbc46f6..7a7deb354 100644 --- a/content/web-ui/hub_administration/extending-mission-portal.markdown +++ b/content/web-ui/hub_administration/extending-mission-portal.markdown @@ -42,10 +42,10 @@ of Mission Portal. ```html {file="file_name.html"}
-
-

PAGE TITLE

-
+
+

PAGE TITLE

+
- +
``` diff --git a/content/web-ui/hub_administration/extending-query-builder.markdown b/content/web-ui/hub_administration/extending-query-builder.markdown index 6606b4874..fb8fe9ce9 100644 --- a/content/web-ui/hub_administration/extending-query-builder.markdown +++ b/content/web-ui/hub_administration/extending-query-builder.markdown @@ -89,37 +89,37 @@ Below you can see an example of hosts table representation as JSON element. Each element has a key and a value. When you create your own JSON element please use a unique key. The value is a JSON object, please see explanations below. The element's key should be equal to `TableID`. -* **TableID** *(string)* - Table id, can be the same as main element key, should be unique. -* **Keys** *(json)* - Table keys, describe there primary key, emp.: `{'primary_key': 'HostKey'}`. - Primary key is case-sensitive. `primary_key` is the only possible key in `Keys` structure. -* **Label** *(string)* - Label contains a table's name that will be shown on the UI. Not necessary to use a real table name, - it can be an alias for better representation. -* **Fields** *(json)* - JSON object that contains table columns. - - **Fields structure:** +- **TableID** _(string)_ + Table id, can be the same as main element key, should be unique. +- **Keys** _(json)_ + Table keys, describe there primary key, emp.: `{'primary_key': 'HostKey'}`. + Primary key is case-sensitive. `primary_key` is the only possible key in `Keys` structure. +- **Label** _(string)_ + Label contains a table's name that will be shown on the UI. Not necessary to use a real table name, + it can be an alias for better representation. +- **Fields** _(json)_ + JSON object that contains table columns. + + **Fields structure:** Fields object is presented as JSON, where key is unique table's key and value is JSON representation of table column properties. The element's key should be equal to `sqlField` -* **name** *(string)* - Field's name -* **label** *(string)* - Label contains a field's name that will be shown on the UI. Not necessary to use a real field name, - an alias can be used for better representation. -* **inputType** *(string)* - Type of input fields, will be used to create filter input for this field. Allowed values: `text`, `textarea`, - `select` - a drop-down list, - `multiple` - a drop-down list that allows multiple selections, `radio`, `checkboxes` -* **table** *(string)* - Field's table name -* **sqlField** *(string)* - Concatenation of `table name`.`field name`. Emp.: `Hosts.FirstReportTimeStamp` -* **dataType** *(string)* - Column's database type, allowed values: `timestamp`, `string`, `real`, `integer`, `array` +- **name** _(string)_ + Field's name +- **label** _(string)_ + Label contains a field's name that will be shown on the UI. Not necessary to use a real field name, + an alias can be used for better representation. +- **inputType** _(string)_ + Type of input fields, will be used to create filter input for this field. Allowed values: `text`, `textarea`, + `select` - a drop-down list, + `multiple` - a drop-down list that allows multiple selections, `radio`, `checkboxes` +- **table** _(string)_ + Field's table name +- **sqlField** _(string)_ + Concatenation of `table name`.`field name`. Emp.: `Hosts.FirstReportTimeStamp` +- **dataType** _(string)_ + Column's database type, allowed values: `timestamp`, `string`, `real`, `integer`, `array` After dca.js editing please validate the content of DCA variable (`var DCA =`) in a JSON validation tooling, there are many online tools to do that. Once your content validated and file has saved your changes will appear after diff --git a/content/web-ui/hub_administration/policy-deployment.markdown b/content/web-ui/hub_administration/policy-deployment.markdown index 1778bfed7..3a58acfcd 100644 --- a/content/web-ui/hub_administration/policy-deployment.markdown +++ b/content/web-ui/hub_administration/policy-deployment.markdown @@ -43,6 +43,7 @@ You must have the following: - a [git refspec](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec) Then one of these combinations: + - a git username and password in the case of an ssh-based or git-based URL (no private key required) - a passphrase-less [private key](https://git-scm.com/book/en/v2/Git-on-the-Server-Generating-Your-SSH-Public-Key) (no username or password required) - a [github token](https://git-scm.com/book/en/v2/Git-Internals-The-Refspec) which is really just a username and password but for github this signifies read-only access (no private key required) diff --git a/content/web-ui/measurements.markdown b/content/web-ui/measurements.markdown index 8ce52e6c9..0b8343626 100644 --- a/content/web-ui/measurements.markdown +++ b/content/web-ui/measurements.markdown @@ -11,9 +11,9 @@ Measurements allows you to get an overview of specific metrics on your hosts ove If multiple hosts are selected in the menu on the left, then you can select one of three key measurements that is then displayed for all hosts: -* load average -* Disk free (in %) -* CPU(ALL) (in %) +- load average +- Disk free (in %) +- CPU(ALL) (in %) You can reduce the number of graphs by selecting a sub-set of hosts from the menu on the left. If only a single host is selected, then a number of graphs for various measurements will be displayed for this host. Which exact measurements are reported depends on how [`cf-monitord`][component-cf-monitord] is configured and extended via [`measurements`][promise-type-measurements] promises. @@ -24,5 +24,5 @@ Clicking on an individual graph allows to select different time spans for which If you don't see any data, make sure that: -* [`cf-monitord`][component-cf-monitord] is running on your hosts. -* [`cf-hub`][cf-hub] has access to collecting the monitoring data from your hosts. See [Configuring Enterprise Measurement and Monitoring Collection][mpf-configure-measurement-collection] in the Masterfiles Policy Framework. +- [`cf-monitord`][component-cf-monitord] is running on your hosts. +- [`cf-hub`][cf-hub] has access to collecting the monitoring data from your hosts. See [Configuring Enterprise Measurement and Monitoring Collection][mpf-configure-measurement-collection] in the Masterfiles Policy Framework. diff --git a/content/web-ui/settings.markdown b/content/web-ui/settings.markdown index dad91d9ba..0658e7cc1 100644 --- a/content/web-ui/settings.markdown +++ b/content/web-ui/settings.markdown @@ -20,14 +20,14 @@ drop down in the top right hand corner. User settings and preferences allows the CFEngine Enterprise administrator to change various options, including: -* Turn on or off RBAC - * When RBAC is disabled any user can see a host that has reported classes - * Note, administrative functions like the ability to delete hosts are not +- Turn on or off RBAC + - When RBAC is disabled any user can see a host that has reported classes + - Note, administrative functions like the ability to delete hosts are not affected by this setting and hosts that have no reported classes are never shown. -* Unreachable host threshold -* Number of samples used to identify a duplicate identity -* Log level +- Unreachable host threshold +- Number of samples used to identify a duplicate identity +- Log level ## User management @@ -65,24 +65,30 @@ Users without a role will not be able to see any hosts in Mission Portal. Here is a set of example roles, users and the impact on each user will be able to view. ### Example roles + Role **suse**: + - Class include: `SUSE` - Class exclude: empty Role **cfengine_3**: + - Class include: `cfengine_3` - Class exclude: empty Role **no_windows** + - Class include: `cfengine_3` - Class exclude: `windows` Role **windows_ubuntu** + - Class include: `windows` - Class include: `ubuntu` - Class exclude: empty ### Example users + User one has role `SUSE`. User two has roles `no_windows` and `cfengine_3`. @@ -90,6 +96,7 @@ User two has roles `no_windows` and `cfengine_3`. User three has roles `windows_ubuntu` and `no_windows`. ### What reports each user can view + A report shared with `SUSE` and `no_windows` will not be seen by any of the listed users. A report shared with `no_windows` and `cfengine_3` will only be seen by user two. @@ -97,6 +104,7 @@ A report shared with `no_windows` and `cfengine_3` will only be seen by user two A report shared with `SUSE` will be seen by user one. ### Which hosts each user can view + User one will only be able to see hosts that report the `SUSE` class. User two will be able to see all hosts that have **not** reported the `windows` class. @@ -105,8 +113,8 @@ User three will only be able to see hosts that have reported the `ubuntu` class. ### Predefined roles -* ```admin``` - The admin role can see everything and do anything. -* ```cf_remoteagent``` - This role allows execution of `cf-runagent`. +- `admin` - The admin role can see everything and do anything. +- `cf_remoteagent` - This role allows execution of `cf-runagent`. ### Default role @@ -183,15 +191,14 @@ Mission portal can authenticate against an external directory. ### LDAP groups syncing - LDAP group syncing can be turned on by clicking the corresponding checkbox - - - User group attribute must be provided to obtain groups from an LDAP user entity. + - User group attribute must be provided to obtain groups from an LDAP user entity. The default value for Active Directory is `memberOf`. The group name will be taken from `cn` attribute - - List of groups to sync, names must match in LDAP/MP. Each role should be added on a new line. - - Click `Perform sync on every login` checkbox to synchronize user roles on every login, otherwise + - List of groups to sync, names must match in LDAP/MP. Each role should be added on a new line. + - Click `Perform sync on every login` checkbox to synchronize user roles on every login, otherwise roles will be assigned to a user only on sign-up (first login). -**Note:** Roles *must* be created in Mission Portal. Enabling LDAP group sync +**Note:** Roles _must_ be created in Mission Portal. Enabling LDAP group sync will not result in addition or removal of Mission Portal roles. **See also:** [LDAP authentication REST API][LDAP authentication API], [Role management][Settings#Role management] From 7e86e42e4262ee8a12b77790e9d199b557363c9c Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Mon, 4 Aug 2025 16:24:57 +0200 Subject: [PATCH 2/3] GH Actions: Run prettier on markdown files Signed-off-by: Ole Herman Schumacher Elgesem --- .github/workflows/formatting.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/formatting.yml b/.github/workflows/formatting.yml index eb4282c71..baa6c4ac7 100644 --- a/.github/workflows/formatting.yml +++ b/.github/workflows/formatting.yml @@ -21,11 +21,17 @@ jobs: python-version: "3.12" - name: Install tools run: | + npm install --global prettier pipx install cfengine black - name: Run formatting command to (hopefully not) make changes run: | - cfengine dev docs-format + # TODO: We can integrate these commands into cfengine dev docs-format + # https://northerntech.atlassian.net/browse/CFE-4572 + # TODO: There are (small) diffs between cfbs pretty and prettier + # https://northerntech.atlassian.net/browse/CFE-4571 + find . -name '*.markdown' -type f | parallel -j16 prettier -w {} black . + cfengine dev docs-format - name: Check output.log file for warnings run: | ! grep WARNING output.log From 414df2ab2e382efd707eafd434fa3c05c018003e Mon Sep 17 00:00:00 2001 From: Ole Herman Schumacher Elgesem Date: Mon, 4 Aug 2025 16:36:29 +0200 Subject: [PATCH 3/3] Manual formatting fixes Signed-off-by: Ole Herman Schumacher Elgesem --- .../changes-api-usage.markdown | 2 +- .../installation-guide.markdown | 8 ++--- ...ory_remediate_sec_vulnerabilities.markdown | 32 +++++++++---------- content/overview/how-cfengine-works.markdown | 4 +-- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/content/api/enterprise-api-examples/changes-api-usage.markdown b/content/api/enterprise-api-examples/changes-api-usage.markdown index 6388b7b2c..eeae97b6e 100644 --- a/content/api/enterprise-api-examples/changes-api-usage.markdown +++ b/content/api/enterprise-api-examples/changes-api-usage.markdown @@ -30,7 +30,7 @@ curl --user admin:admin 'https://test.cfengine.com/api/v2/changes/policy/count?i Show all _vacuumdb_ executions within last 24 hours executed on hosts reporting the `policy_server` or `test_cfengine_com` class. -Example is searching for changes that are performed by _policy_server_ machines that execute _commands_ promise with command _/var/cfengine/bin/vacuumdb%_ - there is `%` sign at the end which is a wildcard as `vacuumdb` is executed with different options across policy. +Example is searching for changes that are performed by _policy_server_ machines that execute _commands_ promise with command `/var/cfengine/bin/vacuumdb%` - there is `%` sign at the end which is a wildcard as `vacuumdb` is executed with different options across policy. **Request** diff --git a/content/examples/tutorials/high-availability/installation-guide.markdown b/content/examples/tutorials/high-availability/installation-guide.markdown index 04d62c42b..0b30e559c 100644 --- a/content/examples/tutorials/high-availability/installation-guide.markdown +++ b/content/examples/tutorials/high-availability/installation-guide.markdown @@ -27,7 +27,7 @@ all your CFEngine clients in case of failover. - We recommend having one shared IP address assigned for interface where MP is accessible (optionally) and one where PostgreSQL replication is configured (mandatory). - Both active and passive hub machines must be configured so that host names are different. -- Basic hostname resolution works (hub names can be placed in _/etc/hosts_ or DNS configured). +- Basic hostname resolution works (hub names can be placed in `/etc/hosts` or DNS configured). ### Example configuration used in this tutorial @@ -196,7 +196,7 @@ performed on the active (node1), the passive (node2) or both nodes. chown -R cfpostgres:cfpostgres /var/cfengine/state/pg/{data/pg_arch,tmp} ``` - 2. Modify the _/var/cfengine/state/pg/data/postgresql.conf_ configuration file to set the + 2. Modify the `/var/cfengine/state/pg/data/postgresql.conf` configuration file to set the following options accordingly (**uncomment the lines if they are commented out**): ``` @@ -507,7 +507,7 @@ performed on the active (node1), the passive (node2) or both nodes. **IMPORTANT:** Copy over only the hashes, without the `SHA=` prefix. -6. **On both nodes,** add the following class definition to the _/var/cfengine/masterfiles/def.json_ +6. **On both nodes,** add the following class definition to the `/var/cfengine/masterfiles/def.json` file to enable HA: ```json {file="def.json"} @@ -608,7 +608,7 @@ performed on the active (node1), the passive (node2) or both nodes. 3. After verifying that replication is finished and data is synchronized between active database node and replica node (or once node1 and node2 are both down) promote PostgreSQL to exit recovery and begin read-write operations `cd /tmp && su cfpostgres -c "/var/cfengine/bin/pg_ctl -c -w -D /var/cfengine/state/pg/data -l /var/log/postgresql.log promote"`. -4. In order to make failover process as easy as possible there is `"failover_to_replication_node_enabled"` class defined both in _/var/cfengine/masterfiles/controls/VERSION/def.cf_ and _/var/cfengine/masterfiles/controls/VERSION/update_def.cf_. In order to stat collecting reports and serving policy from 3rd node uncomment the line defining mentioned class. +4. In order to make failover process as easy as possible there is `"failover_to_replication_node_enabled"` class defined both in `/var/cfengine/masterfiles/controls/VERSION/def.cf` and `/var/cfengine/masterfiles/controls/VERSION/update_def.cf`. In order to stat collecting reports and serving policy from 3rd node uncomment the line defining mentioned class. **IMPORTANT:** Please note that as long as any of the active or passive cluster nodes is accessible by client to be contacted, failover to 3rd node is not possible. If the active or passive node is running and failover to 3rd node is required make sure to disable network interfaces where clients are bootstrapped to so that clients won't be able to access any other node than disaster-recovery. diff --git a/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown b/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown index 22c972ec2..961ff45b8 100644 --- a/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown +++ b/content/examples/tutorials/report_inventory_remediate_sec_vulnerabilities.markdown @@ -76,30 +76,30 @@ bundle agent inventory_CVE_2014_6271 ### What does this inventory policy do? Meta type promises are used to attach additional information to bundles. We -have set 'description' so that future readers of the policy will know what the +have set `description` so that future readers of the policy will know what the policy is for and how to get more information on the vulnerability. For -the sake of simplicity in this example set 'autorun' as a tag to the bundle. +the sake of simplicity in this example set `autorun` as a tag to the bundle. This makes the bundle available for automatic activation when using the autorun feature in the Masterfiles Policy Framework. Next we set the paths to the binaries that we will use to exeucte our test -command. As of this writing the paths for 'env' and 'echo' are both in the -standard libraries paths bundle, but 'bash' is not. Note that you may need to +command. As of this writing the paths for `env` and `echo` are both in the +standard libraries paths bundle, but `bash` is not. Note that you may need to adjust the path to bash for your platforms. Then we run our test command and -place the command output into the 'test_result' variable. Since we have no -_CVE_2014_6271_ class defined yet, the next promise to set the variable -'vulnerable' to 'CVE-2014-6271' will be skipped on the first pass. Then the -classes type promise is evaluated and defines the class _CVE_2014_6271_ if the -output matches the regular expression 'vulnerable.\*'. Finally the reports are -evaluated before starting the second pass. If the class 'DEBUG' or -'DEBUG_inventory_CVE_2014_6271' is set the test command output will be shown, +place the command output into the `test_result` variable. Since we have no +`CVE_2014_6271` class defined yet, the next promise to set the variable +`vulnerable` to `CVE-2014-6271` will be skipped on the first pass. Then the +classes type promise is evaluated and defines the class `CVE_2014_6271` if the +output matches the regular expression `vulnerable.\*`. Finally the reports are +evaluated before starting the second pass. If the class `DEBUG` or +`DEBUG_inventory_CVE_2014_6271` is set the test command output will be shown, and if the vulnerability is present agent is running in inform or verbose mode message indicating the host is vulnerable along with the description will be output. -On the second pass only that variable 'vulnerable' will be set with the value -'CVE-2014-6271' if the host is vulnerable. Note how this variable tagged with -'inventory' and 'attribute_name='. These are special meta tags that CFEngine +On the second pass only that variable `vulnerable` will be set with the value +`CVE-2014-6271` if the host is vulnerable. Note how this variable tagged with +`inventory` and `attribute_name=`. These are special meta tags that CFEngine Enterprise uses in order to display information. ### Deploy the policy @@ -172,9 +172,9 @@ bundle agent remediate_CVE_2014_6271 ### What does this remediation policy do? -For simplicity of the example this policy defines the class allow_update on hub +For simplicity of the example this policy defines the class `allow_update` on hub and host001, but you could use any class that makes sense to you. If the -allow_update class is set, and the class _CVE_2014_6271_ is defined (indicating +`allow_update` class is set, and the class `CVE_2014_6271` is defined (indicating the host is vulnerable) then the policy ensures that bash is updated to the latest version available. diff --git a/content/overview/how-cfengine-works.markdown b/content/overview/how-cfengine-works.markdown index 4caebed42..9ba8514b8 100644 --- a/content/overview/how-cfengine-works.markdown +++ b/content/overview/how-cfengine-works.markdown @@ -196,8 +196,8 @@ The four mission phases are sometimes referred to as - Deploy Deploying really means launching the policy into production. In CFEngine you - simply publish your policy (in CFEngine parlance these are `promise - proposals`) and the machines see the new proposals and can adjust + simply publish your policy (in CFEngine parlance these are `promise proposals`) + and the machines see the new proposals and can adjust accordingly. Each machine runs an agent that is capable of keeping the system on course and maintaining it over time without further assistance.