From 807acdce4ed595e12e198b42d849f9eef516c792 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Tue, 26 May 2026 10:44:49 -0400 Subject: [PATCH 1/3] feat: migrate HTTP API docs from openvox_8x to openvox-server_8x Resolves phase 1-4 of issue #250: - Move 9 Puppet v3 API pages from docs/_openvox_8x/http_api/ into docs/_openvox-server_8x/, updating front matter and schema links - Remove 3 deleted-endpoint pages (resource_type, environment, status) and delete the entire docs/_openvox_8x/http_api/ directory - Write 3 new CA v1 endpoint pages from scratch (expirations, renewal, sign), verified against OpenVox Server source and a live Vagrant env - Restructure openvox-server_8x nav into a single "HTTP API" parent with Puppet v3, Puppet v4, and CA v1 sub-groups - Replace openvox_8x HTTP API nav with a cross-link to openvox-server Closes #250 Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Michael Harp --- _data/nav/openvox-server_8x.yml | 148 ++++--- _data/nav/openvox_8x.yml | 54 +-- .../http_api_index.markdown | 67 ++-- docs/_openvox-server_8x/http_catalog.md | 246 ++++++++++++ .../http_certificate_expirations.md | 59 +++ .../http_certificate_renewal.md | 88 ++++ .../http_certificate_sign.md | 138 +++++++ .../http_environments.md | 24 +- .../http_facts.md | 23 +- .../http_file_bucket_file.md | 51 +-- docs/_openvox-server_8x/http_file_content.md | 78 ++++ .../http_file_metadata.md | 211 +++++----- .../http_node.md | 24 +- .../http_report.md | 55 ++- docs/_openvox-server_8x/pson.md | 65 +++ docs/_openvox_8x/http_api/http_api_index.md | 192 --------- docs/_openvox_8x/http_api/http_catalog.md | 376 ------------------ docs/_openvox_8x/http_api/http_certificate.md | 115 ------ .../http_api/http_certificate_request.md | 177 --------- .../http_certificate_revocation_list.md | 200 ---------- .../http_api/http_certificate_status.md | 136 ------- docs/_openvox_8x/http_api/http_environment.md | 87 ---- .../_openvox_8x/http_api/http_file_content.md | 81 ---- .../http_api/http_resource_type.md | 236 ----------- docs/_openvox_8x/http_api/http_status.md | 47 --- docs/_openvox_8x/http_api/pson.md | 69 ---- 26 files changed, 980 insertions(+), 2067 deletions(-) create mode 100644 docs/_openvox-server_8x/http_catalog.md create mode 100644 docs/_openvox-server_8x/http_certificate_expirations.md create mode 100644 docs/_openvox-server_8x/http_certificate_renewal.md create mode 100644 docs/_openvox-server_8x/http_certificate_sign.md rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_environments.md (58%) rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_facts.md (71%) rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_file_bucket_file.md (59%) create mode 100644 docs/_openvox-server_8x/http_file_content.md rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_file_metadata.md (53%) rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_node.md (79%) rename docs/{_openvox_8x/http_api => _openvox-server_8x}/http_report.md (65%) create mode 100644 docs/_openvox-server_8x/pson.md delete mode 100644 docs/_openvox_8x/http_api/http_api_index.md delete mode 100644 docs/_openvox_8x/http_api/http_catalog.md delete mode 100644 docs/_openvox_8x/http_api/http_certificate.md delete mode 100644 docs/_openvox_8x/http_api/http_certificate_request.md delete mode 100644 docs/_openvox_8x/http_api/http_certificate_revocation_list.md delete mode 100644 docs/_openvox_8x/http_api/http_certificate_status.md delete mode 100644 docs/_openvox_8x/http_api/http_environment.md delete mode 100644 docs/_openvox_8x/http_api/http_file_content.md delete mode 100644 docs/_openvox_8x/http_api/http_resource_type.md delete mode 100644 docs/_openvox_8x/http_api/http_status.md delete mode 100644 docs/_openvox_8x/http_api/pson.md diff --git a/_data/nav/openvox-server_8x.yml b/_data/nav/openvox-server_8x.yml index 6e642ad06..81f56c743 100644 --- a/_data/nav/openvox-server_8x.yml +++ b/_data/nav/openvox-server_8x.yml @@ -66,64 +66,98 @@ link: tuning_guide.html - text: Scaling OpenVox Server with compilers link: scaling_puppet_server.html -- text: Administrative API endpoints +- text: HTTP API items: - - text: Environment cache - link: admin-api/v1/environment-cache.html - - text: JRuby pool - link: admin-api/v1/jruby-pool.html -- text: CA API endpoints - items: - - text: Certificate - link: http_certificate.html - - text: Certificate signing request - link: http_certificate_request.html - - text: Certificate status - link: http_certificate_status.html - - text: Certificate revocation list - link: http_certificate_revocation_list.html -- text: Server-specific Puppet API endpoints - items: - - text: Environment classes - link: puppet-api/v3/environment_classes.html - - text: Environment modules - link: puppet-api/v3/environment_modules.html - - text: Environment transports - link: puppet-api/v3/environment_transports.html - - text: Compile endpoint - link: puppet-api/v3/compile.html - - text: Static file content - link: puppet-api/v3/static_file_content.html - - text: File content - link: puppet-api/v3/file_content.html - - text: Tasks overview - link: puppet-api/v3/tasks.html - - text: Tasks details - link: puppet-api/v3/task_detail.html - - text: Plans overview - link: puppet-api/v3/plans.html - - text: Plans details - link: puppet-api/v3/plan_detail.html - - text: Catalog endpoint - link: puppet-api/v4/catalog.html -- text: Status API endpoints - items: - - text: Services endpoint - link: status-api/v1/services.html - - text: Simple endpoint - link: status-api/v1/simple.html -- text: Metrics - items: - - text: Monitoring OpenVox Server metrics - link: puppet_server_metrics.html - - text: HTTP client metrics - link: http_client_metrics.html - - text: Applying metrics to improve performance - link: puppet_server_metrics_performance.html - - text: v1 metrics API - link: metrics-api/v1/metrics_api.html - - text: v2 (Jolokia) metrics API - link: metrics-api/v2/metrics_api.html + - text: HTTP API overview + link: http_api_index.html + - text: PSON + link: pson.html + - text: Puppet v3 API + items: + - text: Catalog + link: http_catalog.html + - text: Node + link: http_node.html + - text: Facts + link: http_facts.html + - text: File bucket file + link: http_file_bucket_file.html + - text: File content + link: http_file_content.html + - text: File metadata + link: http_file_metadata.html + - text: Report + link: http_report.html + - text: Environments + link: http_environments.html + - text: Puppet v4 API + items: + - text: Catalog + link: puppet-api/v4/catalog.html + - text: CA v1 API + items: + - text: Certificate + link: http_certificate.html + - text: Certificate request + link: http_certificate_request.html + - text: Certificate status + link: http_certificate_status.html + - text: Certificate revocation list + link: http_certificate_revocation_list.html + - text: Certificate clean + link: http_certificate_clean.html + - text: Certificate expirations + link: http_certificate_expirations.html + - text: Certificate renewal + link: http_certificate_renewal.html + - text: Bulk certificate sign + link: http_certificate_sign.html + - text: Server-specific API + items: + - text: Environment classes + link: puppet-api/v3/environment_classes.html + - text: Environment modules + link: puppet-api/v3/environment_modules.html + - text: Environment transports + link: puppet-api/v3/environment_transports.html + - text: Compile endpoint + link: puppet-api/v3/compile.html + - text: Static file content + link: puppet-api/v3/static_file_content.html + - text: File content + link: puppet-api/v3/file_content.html + - text: Tasks overview + link: puppet-api/v3/tasks.html + - text: Tasks details + link: puppet-api/v3/task_detail.html + - text: Plans overview + link: puppet-api/v3/plans.html + - text: Plans details + link: puppet-api/v3/plan_detail.html + - text: Admin API + items: + - text: Environment cache + link: admin-api/v1/environment-cache.html + - text: JRuby pool + link: admin-api/v1/jruby-pool.html + - text: Status API + items: + - text: Services endpoint + link: status-api/v1/services.html + - text: Simple endpoint + link: status-api/v1/simple.html + - text: Metrics + items: + - text: Monitoring OpenVox Server metrics + link: puppet_server_metrics.html + - text: HTTP client metrics + link: http_client_metrics.html + - text: Applying metrics to improve performance + link: puppet_server_metrics_performance.html + - text: v1 metrics API + link: metrics-api/v1/metrics_api.html + - text: v2 (Jolokia) metrics API + link: metrics-api/v2/metrics_api.html - text: Developer information items: - text: Developer debugging diff --git a/_data/nav/openvox_8x.yml b/_data/nav/openvox_8x.yml index 0b755337b..6cd79bfb4 100644 --- a/_data/nav/openvox_8x.yml +++ b/_data/nav/openvox_8x.yml @@ -395,58 +395,8 @@ link: "man/status.html" - text: HTTP API items: - - text: Index - link: "http_api/http_api_index.html" - - text: PSON - link: "http_api/pson.html" - - text: Catalog - link: "http_api/http_catalog.html" - - text: Node - link: "http_api/http_node.html" - - text: File bucket file - link: "http_api/http_file_bucket_file.html" - - text: File content - link: "http_api/http_file_content.html" - - text: File metadata - link: "http_api/http_file_metadata.html" - - text: Report - link: "http_api/http_report.html" - - text: Environments - link: "http_api/http_environments.html" - - text: Resource type - link: "http_api/http_resource_type.html" - - text: Status - link: "http_api/http_status.html" - - text: Certificate - link: "http_api/http_certificate.html" - - text: Certificate signing requests - link: "http_api/http_certificate_request.html" - - text: Certificate status - link: "http_api/http_certificate_status.html" - - text: Certificate revocation list - link: "http_api/http_certificate_revocation_list.html" - - text: catalog.json - link: "schemas/catalog.json" - - text: environments.json - link: "schemas/environments.json" - - text: error.json - link: "schemas/error.json" - - text: facts.json - link: "schemas/facts.json" - - text: file_metadata.json - link: "schemas/file_metadata.json" - - text: host.json - link: "schemas/host.json" - - text: json-meta-schema.json - link: "schemas/json-meta-schema.json" - - text: node.json - link: "schemas/node.json" - - text: report.json - link: "schemas/report.json" - - text: resource_type.json - link: "schemas/resource_type.json" - - text: status.json - link: "schemas/status.json" + - text: OpenVox Server HTTP API + link: "/openvox-server/latest/http_api_index.html" - text: SSL and certificates items: - text: Using an external CA diff --git a/docs/_openvox-server_8x/http_api_index.markdown b/docs/_openvox-server_8x/http_api_index.markdown index 33532fe83..6c0cee1b6 100644 --- a/docs/_openvox-server_8x/http_api_index.markdown +++ b/docs/_openvox-server_8x/http_api_index.markdown @@ -25,12 +25,12 @@ All configuration endpoints are prefixed with `/puppet`, while all CA endpoints ### Authorization -Authorization for `/puppet` and `/puppet-ca` endpoints is controlled with [OpenVox Server's `auth.conf` authorization system](./config_file_auth.html). +Authorization for `/puppet` and `/puppet-ca` endpoints is controlled with [OpenVox Server's `auth.conf` authorization system](config_file_auth.html). ## OpenVox V3 HTTP API The OpenVox agent application uses several network services to manage systems. These services are all grouped under the `/puppet` API. -Other tools can access these services and use the OpenVox Servers's data for other purposes. +Other tools can access these services and use the OpenVox Server's data for other purposes. The V3 API contains endpoints of two types: those that are based on dispatching to OpenVox's internal "indirector" framework, and those that are not (namely the [environments endpoint](#environments-endpoint)). @@ -44,52 +44,47 @@ Using this API requires significant understanding of how OpenVox's internal serv ### Configuration management services -The OpenVox agent application directly uses these servcies to manage the configuration of a node. +The OpenVox agent application directly uses these services to manage the configuration of a node. These endpoints accept payload formats formatted as JSON by default (MIME type of `application/json`), except for `File Content` and `File Bucket File`, which always use `application/octet-stream`. > **Note:** Legacy PSON (MIME type of `text/pson`) is still an available format, but should be used only as a fallback for binary content. -- [Facts](/openvox/latest/http_api/http_facts.html) -- [Catalog](/openvox/latest/http_api/http_catalog.html) -- [Node](/openvox/latest/http_api/http_node.html) -- [File bucket file](/openvox/latest/http_api/http_file_bucket_file.html) -- [File content](/openvox/latest/http_api/http_file_content.html) -- [File metadata](/openvox/latest/http_api/http_file_metadata.html) -- [Report](/openvox/latest/http_api/http_report.html) +- [Facts](http_facts.html) +- [Catalog](http_catalog.html) +- [Node](http_node.html) +- [File bucket file](http_file_bucket_file.html) +- [File content](http_file_content.html) +- [File metadata](http_file_metadata.html) +- [Report](http_report.html) -### Informational services - -These services are not directly used by OpenVox agent, but can be used by other tools. - -- [Status](/openvox/latest/http_api/http_status.html) - -> **Note:** The [OpenVox Server status API](#openvox-server-specific-endpoints) provides more detail and features. +> **Note:** The [Puppet v4 catalog API](puppet-api/v4/catalog.html) is preferred for new integrations. It does +> not require facts to be submitted as part of the catalog request. ### Environments endpoint -The `/puppet/v3/environments` endpoint uses a different format than the configuration management and informational services endpoints. +The `/puppet/v3/environments` endpoint uses a different format than the configuration management endpoints. The endpoint accepts only payloads formatted as JSON, and responds with JSON (MIME type of `application/json`). -- [Environments](/openvox/latest/http_api/http_environments.html) +- [Environments](http_environments.html) ### OpenVox Server-specific endpoints OpenVox Server adds several unique endpoints of its own. They include these additional `/puppet/v3/` endpoints: -- [Environment classes](./puppet-api/v3/environment_classes.html), at `/puppet/v3/environment_classes` -- [Environment modules](./puppet-api/v3/environment_modules.html), at `/puppet/v3/environment_modules` -- [Static file content](./puppet-api/v3/static_file_content.html), at `/puppet/v3/static_file_content` +- [Environment classes](puppet-api/v3/environment_classes.html), at `/puppet/v3/environment_classes` +- [Environment modules](puppet-api/v3/environment_modules.html), at `/puppet/v3/environment_modules` +- [Static file content](puppet-api/v3/static_file_content.html), at `/puppet/v3/static_file_content` It also includes these unique APIs, with endpoints containing other URL prefixes: -- [Status API](./status-api/v1/services.html), at `/status/v1/services` -- [Metrics v1 (mbeans) API](./metrics-api/v1/metrics_api.html), at `/metrics/v1/mbeans` -- [Metrics v2 (Jolokia) API](./metrics-api/v2/metrics_api.html), at `/metrics/v2/` +- [Status API](status-api/v1/services.html), at `/status/v1/services` +- [Metrics v1 (mbeans) API](metrics-api/v1/metrics_api.html), at `/metrics/v1/mbeans` +- [Metrics v2 (Jolokia) API](metrics-api/v2/metrics_api.html), at `/metrics/v2/` - Admin API, at `/puppet-admin-api/v1/`: - - [Environment cache](./admin-api/v1/environment-cache.html), at `/puppet-admin-api/v1/environment-cache` - - [JRuby pool](./admin-api/v1/jruby-pool.html), at `/puppet-admin-api/v1/jruby-pool` + - [Environment cache](admin-api/v1/environment-cache.html), at `/puppet-admin-api/v1/environment-cache` + - [JRuby pool](admin-api/v1/jruby-pool.html), at `/puppet-admin-api/v1/jruby-pool` ### Error responses @@ -109,7 +104,7 @@ Except for HEAD requests, error responses contain a body of a uniform JSON objec - `message`: (`String`) A human-readable message explaining the error. - `issue_kind`: (`String`) A unique label to identify the error class. -OpenVOx provides a [JSON schema for error objects](/openvox/latest/schemas/error.json). Endpoints implemented by OpenVox Server have a different error schema: +OpenVox provides a [JSON schema for error objects](/openvox/latest/schemas/error.json). Endpoints implemented by OpenVox Server have a different error schema: ```json { @@ -136,18 +131,22 @@ The following documents specify what is available and how to interact with it. ### SSL certificate-related services -These endpoints accept only plain-text payload formats. Historically, OpenVox has used the MIME type `s` to mean `text/plain`. In now uses `text/plain`, but continues to accept `s` as an equivalent. +These endpoints accept only plain-text payload formats. Historically, OpenVox has used the MIME type `s` to mean `text/plain`. It now uses `text/plain`, but continues to accept `s` as an equivalent. -- [Certificate](./http_certificate.html) -- [Certificate Signing Requests](./http_certificate_request.html) -- [Certificate Status](./http_certificate_status.html) -- [Certificate Revocation List](./http_certificate_revocation_list.html) +- [Certificate](http_certificate.html) +- [Certificate Signing Requests](http_certificate_request.html) +- [Certificate Status](http_certificate_status.html) +- [Certificate Revocation List](http_certificate_revocation_list.html) +- [Certificate Clean](http_certificate_clean.html) +- [Certificate Expirations](http_certificate_expirations.html) +- [Certificate Renewal](http_certificate_renewal.html) +- [Bulk Certificate Sign](http_certificate_sign.html) ## Serialization formats OpenVox sends messages using several serialization formats. Not all REST services support all of the formats. - [JSON](https://tools.ietf.org/html/rfc7159) -- [PSON](/openvox/latest/http_api/pson.html) +- [PSON](pson.html) (deprecated — see the PSON page for details) `YAML` was supported in earlier versions of OpenVox, but is no longer for security reasons. diff --git a/docs/_openvox-server_8x/http_catalog.md b/docs/_openvox-server_8x/http_catalog.md new file mode 100644 index 000000000..8aeec58d7 --- /dev/null +++ b/docs/_openvox-server_8x/http_catalog.md @@ -0,0 +1,246 @@ +--- +layout: default +title: "OpenVox Server HTTP API: Catalog (v3)" +--- + +## Catalog + +> **Note:** For new integrations, prefer the [Puppet v4 catalog API](puppet-api/v4/catalog.html). The v4 API is +> more efficient because it does not require facts to be submitted as part of the catalog request. + +The `catalog` endpoint returns a catalog for the specified node name given the provided facts. + +## Find + +Retrieve a catalog. + + POST /puppet/v3/catalog/:nodename + GET /puppet/v3/catalog/:nodename?environment=:environment + +### Supported HTTP Methods + +POST, GET + +### Supported Response Formats + +`application/json`, `text/pson` + +### Notes + +The POST and GET methods are functionally equivalent. Both provide the parameters specified below: POST sends them +in the request body, GET sends them in the query string. + +OpenVox originally used GET; POST was added because some web servers have a maximum URI length of 1024 bytes, which +is easily exceeded with the `facts` parameter. + +The examples below use the POST method. + +### Parameters + +Four parameters should be provided to the POST or GET: + +- `environment`: the environment name. +- `facts_format`: must be `application/json` or `pson`. +- `facts`: serialized JSON or PSON of the facts hash. Since facts can contain `&`, which is also the HTTP query + parameter delimiter, facts are doubly-escaped. +- `transaction_uuid`: a transaction uuid identifying the entire transaction (shows up in the report as well). + +Two optional parameters are required for static catalogs: + +- `static_catalog`: a boolean requesting a static catalog if available; should always be `true`. +- `checksum_type`: a dot-separated list of checksum types supported by the agent, for use in file resources of a + static catalog. The order signifies preference, highest first. + +Optional parameters that may be provided to the POST or GET: + +- `configured_environment`: the environment configured on the client. May be provided to notify an ENC that the + client requested a specific environment which might differ from what the client believes is its current + environment. +- `job_id`: which orchestration job triggered this catalog request. + +### Example Response + +#### Catalog found + + POST /puppet/v3/catalog/elmo.mydomain.com + + environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%257B%2522name%2522%253A%2522elmo.mydomain.com%2522%252C%2522values%2522%253A%257B%2522architecture%2522%253A%2522x86_64%2522%257D%257D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c + + HTTP 200 OK + Content-Type: application/json + + { + "tags": [ + "settings", + "multi_param_class", + "class" + ], + "name": "elmo.mydomain.com", + "version": 1377473054, + "code_id": null, + "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e", + "catalog_format": 1, + "environment": "production", + "resources": [ + { + "type": "Stage", + "title": "main", + "tags": [ + "stage" + ], + "exported": false, + "parameters": { + "name": "main" + } + }, + { + "type": "Class", + "title": "Settings", + "tags": [ + "class", + "settings" + ], + "exported": false + }, + { + "type": "Class", + "title": "main", + "tags": [ + "class" + ], + "exported": false, + "parameters": { + "name": "main" + } + }, + { + "type": "Class", + "title": "Multi_param_class", + "tags": [ + "class", + "multi_param_class" + ], + "line": 10, + "exported": false, + "parameters": { + "one": "hello", + "two": "world" + } + }, + { + "type": "Notify", + "title": "foo", + "tags": [ + "notify", + "foo", + "class", + "multi_param_class" + ], + "line": 4, + "exported": false, + "parameters": { + "message": "One is hello, two is world" + } + } + ], + "edges": [ + { + "source": "Stage[main]", + "target": "Class[Settings]" + }, + { + "source": "Stage[main]", + "target": "Class[main]" + }, + { + "source": "Stage[main]", + "target": "Class[Multi_param_class]" + }, + { + "source": "Class[Multi_param_class]", + "target": "Notify[foo]" + } + ], + "classes": [ + "settings", + "multi_param_class" + ] + } + +#### Static Catalog found + + POST /puppet/v3/catalog/elmo.mydomain.com + + environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%7B%22name%22%3A%22elmo.mydomain.com%22%2C%22values%22%3A%7B%22architecture%22%3A%22x86_64%22%7D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c&static_catalog=true&checksum_type=sha256.md5 + + HTTP 200 OK + Content-Type: application/json + + { + "tags": [ + "settings", + "multi_param_class", + "class" + ], + "name": "elmo.mydomain.com", + "version": 1377473054, + "code_id": "arbitrary_code_id_string", + "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e", + "catalog_format": 1, + "environment": "production", + "resources": [ ... ], + "edges": [ ... ], + "classes": [ + "settings", + "multi_param_class" + ], + "metadata": { + "/tmp/foo": { + "checksum": { + "type": "sha256", + "value": "{sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03" + }, + "content_uri": "puppet:///modules/a_module/files/foo", + "destination": null, + "group": 20, + "links": "manage", + "mode": 420, + "owner": 501, + "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/foo.txt", + "relative_path": null, + "source": "puppet:///modules/a_module/foo", + "type": "file" + } + }, + "recursive_metadata": { + "/tmp/bar": { + "puppet:///modules/a_module/bar": [ + { + "checksum": { + "type": "ctime", + "value": "{ctime}2016-02-19 17:38:36 -0800" + }, + "content_uri": "puppet:///modules/a_module/files/bar", + "destination": null, + "group": 20, + "links": "manage", + "mode": 420, + "owner": 501, + "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/bar", + "relative_path": ".", + "source": null, + "type": "directory" + } + ] + } + } + } + + +## Schema + +In the POST request body (or the GET query), the facts parameter should conform to +[the facts schema.](/openvox/latest/schemas/facts.json) + +A catalog response body conforms to +[the catalog schema.](/openvox/latest/schemas/catalog.json) diff --git a/docs/_openvox-server_8x/http_certificate_expirations.md b/docs/_openvox-server_8x/http_certificate_expirations.md new file mode 100644 index 000000000..eca2ade05 --- /dev/null +++ b/docs/_openvox-server_8x/http_certificate_expirations.md @@ -0,0 +1,59 @@ +--- +layout: default +title: "OpenVox Server CA API: Certificate Expirations" +--- + +## Certificate Expirations + +The `expirations` endpoint returns the `not-after` date for every certificate in the CA bundle and the +`next-update` date of every CRL in the chain. This is useful for monitoring CA infrastructure health and +alerting before CA certificate or CRL expiration causes service disruption. + +## Get + +Retrieve expiration information for the CA bundle and CRL chain. + + GET /puppet-ca/v1/expirations + +### Supported HTTP Methods + +GET + +### Supported Response Formats + +`application/json` + +### Parameters + +None + +### Access + +Any client with a certificate signed by the CA may access this endpoint. Access is controlled by OpenVox +Server's `ca.conf` authorization configuration. + +### Example Response + + GET /puppet-ca/v1/expirations + + HTTP/1.1 200 OK + Content-Type: application/json + + { + "ca-certs": { + "Puppet CA: ca.example.com": "2041-05-15T11:22:16UTC", + "Puppet Root CA: a3f8c1d74b2e05": "2041-05-15T11:22:14UTC" + }, + "crls": { + "Puppet CA: ca.example.com": "2031-05-26T14:36:05UTC", + "Puppet Root CA: a3f8c1d74b2e05": "2041-05-15T11:22:14UTC" + } + } + +The response contains two top-level keys: + +- `ca-certs` — maps each CA certificate's subject name to its `not-after` date. +- `crls` — maps each CRL issuer's subject name to its `next-update` date. + +Timestamps are in UTC. The subject name keys reflect the CN of each certificate in the CA bundle. +Deployments using an intermediate CA will have one entry per CA in the chain, as shown above. diff --git a/docs/_openvox-server_8x/http_certificate_renewal.md b/docs/_openvox-server_8x/http_certificate_renewal.md new file mode 100644 index 000000000..ec5454329 --- /dev/null +++ b/docs/_openvox-server_8x/http_certificate_renewal.md @@ -0,0 +1,88 @@ +--- +layout: default +title: "OpenVox Server CA API: Certificate Renewal" +--- + +## Certificate Renewal + +The `certificate_renewal` endpoint allows an OpenVox agent to automatically renew its own certificate without +requiring an administrator to sign a new CSR. The agent makes the request authenticated with its current +certificate (via mutual TLS), and if auto-renewal is enabled and the certificate was signed by this CA, a new +certificate is returned. + +> **Note:** This endpoint is disabled by default. It requires `certificate-authority.allow-auto-renewal: true` +> in OpenVox Server's CA configuration before it will return anything other than 404. + +## Renew + +Submit a certificate renewal request. + + POST /puppet-ca/v1/certificate_renewal + +The request has no body. OpenVox Server identifies the certificate to renew from the TLS client certificate +presented during the connection. If `allow-header-cert-info` is enabled in the CA settings, the certificate +may instead be provided via the `X-Client-Cert` HTTP header. + +### Supported HTTP Methods + +POST + +### Supported Response Formats + +`text/plain` (PEM-encoded signed certificate) + +### Parameters + +None + +### Configuration + +Two settings in the `certificate-authority` section of OpenVox Server's configuration control this endpoint: + +- `allow-auto-renewal` — must be `true` to enable the endpoint. Defaults to `false`. +- `auto-renewal-cert-ttl` — sets the validity period of the renewed certificate. Defaults to `90d`. + +### Access + +Any client with a certificate signed by the CA may access this endpoint. Access is controlled by OpenVox +Server's `ca.conf` authorization configuration. The endpoint should never be used unauthenticated, as it +requires a valid client certificate to identify the certificate to renew. + +### Responses + +#### Renewal successful + + POST /puppet-ca/v1/certificate_renewal + + HTTP/1.1 200 OK + Content-Type: text/plain + + -----BEGIN CERTIFICATE----- + ... (new signed certificate) ... + -----END CERTIFICATE----- + +The renewed certificate is valid for the period configured in `auto-renewal-cert-ttl`. + +#### Auto-renewal disabled + + HTTP/1.1 404 Not Found + +`certificate-authority.allow-auto-renewal` is not enabled. + +#### Certificate not recognized + + HTTP/1.1 403 Forbidden + Content-Type: text/plain + + Certificate present, but does not match signature + +The certificate presented was not signed by this CA. + +#### No valid certificate in request + + HTTP/1.1 400 Bad Request + Content-Type: text/plain + + No valid certificate found in renewal request + +No client certificate was found in the TLS session or the `X-Client-Cert` header. diff --git a/docs/_openvox-server_8x/http_certificate_sign.md b/docs/_openvox-server_8x/http_certificate_sign.md new file mode 100644 index 000000000..27a5fa887 --- /dev/null +++ b/docs/_openvox-server_8x/http_certificate_sign.md @@ -0,0 +1,138 @@ +--- +layout: default +title: "OpenVox Server CA API: Bulk Certificate Sign" +--- + +## Bulk Certificate Sign + +The `sign` endpoints allow an administrator to sign one or more pending certificate signing requests (CSRs) +in a single API call. These endpoints are alternatives to using the `puppetserver ca sign` CLI command. + +Both endpoints require a client certificate with the `pp_cli_auth: "true"` extension. + +## Sign specific certificates + +Sign one or more pending CSRs by certname. + +```text +POST /puppet-ca/v1/sign +Content-Type: application/json +``` + +The request body must contain a `certnames` array listing the certnames to sign. + +### Supported HTTP Methods + +POST + +### Supported Response Formats + +`application/json` + +### Parameters + +None (certnames are provided in the request body) + +### Access + +Requires a client certificate with the `pp_cli_auth: "true"` certificate extension. Access is controlled by +OpenVox Server's `ca.conf` authorization configuration. + +### Example + +#### Request + +```text +POST /puppet-ca/v1/sign +Content-Type: application/json + +{"certnames": ["one.example.com", "nocsrone.example.com"]} +``` + +#### Response + +```text +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "signed": ["one.example.com"], + "no-csr": ["nocsrone.example.com"], + "signing-errors": [] +} +``` + +The response always contains three arrays: + +- `signed` — certnames whose CSRs were successfully signed. +- `no-csr` — certnames for which no pending CSR was found. +- `signing-errors` — certnames whose CSRs failed one or more validation checks. Checks include + subject alternative name allowance, authorization extension allowance, unrecognized extensions, + and signature validity. Example: + +```text +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "signed": [], + "no-csr": [], + "signing-errors": ["badextension.example.com", "invalidsignature.example.com"] +} +``` + +A `200 OK` is returned even if some certnames appear in `no-csr` or `signing-errors`. A `422 Unprocessable +Entity` is returned if the request body does not conform to the expected schema (for example, if `certnames` +contains non-string values): + +```text +HTTP/1.1 422 Unprocessable Entity +Content-Type: application/json + +{"kind":"schema-violation","submitted":[42],"error":"[(not (instance? java.lang.String 42))]"} +``` + +## Sign all pending certificates + +Sign all currently pending CSRs at once. The server automatically discovers all pending CSRs in the +configured CSR directory — no request body is needed. + +### Supported HTTP Methods + +POST + +### Supported Response Formats + +`application/json` + +### Parameters + +None + +### Access + +Requires a client certificate with the `pp_cli_auth: "true"` certificate extension. Access is controlled by +OpenVox Server's `ca.conf` authorization configuration. + +### Example + +#### Request + +```text +POST /puppet-ca/v1/sign/all +``` + +#### Response + +```text +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "signed": ["one.example.com", "two.example.com"], + "no-csr": [], + "signing-errors": [] +} +``` + +If there are no pending CSRs, the `signed` array is empty and the response is still `200 OK`. diff --git a/docs/_openvox_8x/http_api/http_environments.md b/docs/_openvox-server_8x/http_environments.md similarity index 58% rename from docs/_openvox_8x/http_api/http_environments.md rename to docs/_openvox-server_8x/http_environments.md index 98846affc..d839acaa9 100644 --- a/docs/_openvox_8x/http_api/http_environments.md +++ b/docs/_openvox-server_8x/http_environments.md @@ -1,19 +1,16 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Environments' -canonical: "/puppet/latest/http_api/http_environments.html" +title: "OpenVox Server HTTP API: Environments" --- -Environments -============ +## Environments -The `environments` endpoint allows for enumeration of the environments known to the master. Each environment contains information -about itself like its modulepath, manifest directory, environment timeout, and the config version. -This endpoint is by default accessible to any client with a valid certificate, though this may be changed by `auth.conf`. +The `environments` endpoint allows for enumeration of the environments known to the OpenVox Server. Each environment +contains information about itself such as its modulepath, manifest directory, environment timeout, and the config +version. This endpoint is by default accessible to any client with a valid certificate, though this may be changed +by `auth.conf`. -Get ---- +## Get Get the list of known environments. @@ -48,10 +45,9 @@ None } } -The `environment_timeout` attribute could also be the string "unlimited". +The `environment_timeout` attribute can also be the string `"unlimited"`. -Schema ------- +## Schema An environments response body conforms to -[the environments schema.](../schemas/environments.json) +[the environments schema.](/openvox/latest/schemas/environments.json) diff --git a/docs/_openvox_8x/http_api/http_facts.md b/docs/_openvox-server_8x/http_facts.md similarity index 71% rename from docs/_openvox_8x/http_api/http_facts.md rename to docs/_openvox-server_8x/http_facts.md index 0f56ffd37..47fe3e23b 100644 --- a/docs/_openvox_8x/http_api/http_facts.md +++ b/docs/_openvox-server_8x/http_facts.md @@ -1,17 +1,13 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Facts' -canonical: "/puppet/latest/http_api/http_facts.html" +title: "OpenVox Server HTTP API: Facts" --- -Facts -===== +## Facts The `facts` endpoint allows setting the facts for the specified node name. -Save ----- +## Save Store facts for a node. The request body should contain JSON-formatted facts. @@ -31,8 +27,10 @@ None ### Example -* Note: list of facts was shortened for readability. -* Note: JSON was formatted for readability. +- Note: list of facts was shortened for readability. +- Note: JSON was formatted for readability. + + PUT /puppet/v3/facts/elmo.mydomain.com?environment=env Content-Type: application/json @@ -56,8 +54,7 @@ None HTTP/1.1 200 OK Content-Type: application/json -Schema ------- +## Schema -The representation of facts contained in a PUT body, should adhere to -[the facts schema.](../schemas/facts.json) +The representation of facts contained in a PUT body should adhere to +[the facts schema.](/openvox/latest/schemas/facts.json) diff --git a/docs/_openvox_8x/http_api/http_file_bucket_file.md b/docs/_openvox-server_8x/http_file_bucket_file.md similarity index 59% rename from docs/_openvox_8x/http_api/http_file_bucket_file.md rename to docs/_openvox-server_8x/http_file_bucket_file.md index fb9800048..cef26367a 100644 --- a/docs/_openvox_8x/http_api/http_file_bucket_file.md +++ b/docs/_openvox-server_8x/http_file_bucket_file.md @@ -1,55 +1,45 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: File Bucket File' -canonical: "/puppet/latest/http_api/http_file_bucket_file.html" +title: "OpenVox Server HTTP API: File Bucket File" --- -File Bucket File -============= +## File Bucket File -The `file_bucket_file` endpoint manages the contents of files in the -file bucket. All access to files is managed with the md5 checksum of the -file contents, represented as `:md5`. Where used, `:filename` means the -full absolute path of the file on the client system. This is usually -optional and used as an error check to make sure correct file is -retrieved. The environment is required in all requests but ignored, as -the file bucket does not distinguish between environments. +The `file_bucket_file` endpoint manages the contents of files in the file bucket. All access to files is managed +with the MD5 checksum of the file contents, represented as `:md5`. Where used, `:filename` means the full absolute +path of the file on the client system. This is usually optional and used as an error check to make sure the correct +file is retrieved. The environment is required in all requests but ignored, as the file bucket does not distinguish +between environments. -Find ----- +## Find Retrieve the contents of a file. GET /puppet/v3/file_bucket_file/:md5?environment=:environment GET /puppet/v3/file_bucket_file/:md5/:original_path?environment=:environment -This will return the contents of the file if it's present. If -`:original_path` is provided then the contents will only be sent if the -file was uploaded with the same path at some point. +This will return the contents of the file if it's present. If `:original_path` is provided then the contents will +only be sent if the file was uploaded with the same path at some point. -Head ----- +## Head -Check if a file is present in the filebucket +Check if a file is present in the filebucket. HEAD /puppet/v3/file_bucket_file/:md5?environment=:environment HEAD /puppet/v3/file_bucket_file/:md5/:original_path?environment=:environment This behaves identically to find, only returning headers. -Save ----- +## Save -Save a file to the filebucket +Save a file to the filebucket. PUT /puppet/v3/file_bucket_file/:md5?environment=:environment PUT /puppet/v3/file_bucket_file/:md5/:original_path?environment=:environment -The body should contain the file contents. This saves the file using the -md5 sum of the file contents. If `:original_path` is provided, it adds -the path to a list for the given file. If the md5 sum in the request is -incorrect, the file will be instead saved under the correct checksum. +The body should contain the file contents. This saves the file using the MD5 sum of the file contents. If +`:original_path` is provided, it adds the path to a list for the given file. If the MD5 sum in the request is +incorrect, the file will be saved under the correct checksum instead. ### Supported HTTP Methods @@ -98,8 +88,7 @@ None < < Not Found: Could not find file_bucket_file md5/4949e56d376cc80ce5387e8e89a75396/home/user/wrong_name -Schema ------- +## Schema -A `file_bucket_file` response body is not structured data according to any standard scheme such as -json/yaml, so no schema is applicable. +A `file_bucket_file` response body is not structured data according to any standard scheme such as JSON or YAML, +so no schema is applicable. diff --git a/docs/_openvox-server_8x/http_file_content.md b/docs/_openvox-server_8x/http_file_content.md new file mode 100644 index 000000000..2ade5862f --- /dev/null +++ b/docs/_openvox-server_8x/http_file_content.md @@ -0,0 +1,78 @@ +--- +layout: default +title: "OpenVox Server HTTP API: File Content" +--- + +## File Content + +The `file_content` endpoint returns the contents of the specified file. + +## Find + +Get a file. + + GET /puppet/v3/file_content/:mount_point/:name + +The endpoint path includes a `:mount_point` which can be one of the following types: + +- Custom file serving mounts as specified in `fileserver.conf` — see the Puppet docs on + [configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). +- `modules/` — allows access to the `files` subdirectory of `` — see the Puppet docs on + [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- `plugins` — merges the `lib` directory of every module together. Used for syncing plugins; not intended for + general consumption. Per-module sub-paths cannot be specified. +- `pluginfacts` — merges the `facts.d` directory of every module together. Used for syncing external facts; not + intended for general consumption. Per-module sub-paths cannot be specified. +- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see the Puppet docs on + [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). + +`:name` is the path to the file within the `:mount_point` that is requested. + +### Supported HTTP Methods + +GET + +### Supported Response Formats + +`application/octet-stream` + +### Parameters + +None + +### Responses + +#### File found + + GET /puppet/v3/file_content/modules/example/my_file?environment=env + Accept: application/octet-stream + + HTTP/1.1 200 OK + Content-Type: application/octet-stream + Content-Length: 16 + + this is my file + +#### File not found + + GET /puppet/v3/file_content/modules/example/not_found?environment=env + Accept: application/octet-stream + + HTTP/1.1 404 Not Found + Content-Type: text/plain + + Not Found: Could not find file_content modules/example/not_found + +#### No file name given + + GET /puppet/v3/file_content?environment=env + + HTTP/1.1 400 Bad Request + Content-Type: text/plain + + No request key specified in /puppet/v3/file_content/ + +## Schema + +A `file_content` response body is not structured data according to any standard scheme such as JSON or YAML, +so no schema is applicable. diff --git a/docs/_openvox_8x/http_api/http_file_metadata.md b/docs/_openvox-server_8x/http_file_metadata.md similarity index 53% rename from docs/_openvox_8x/http_api/http_file_metadata.md rename to docs/_openvox-server_8x/http_file_metadata.md index 92cd292df..8e4573430 100644 --- a/docs/_openvox_8x/http_api/http_file_metadata.md +++ b/docs/_openvox-server_8x/http_file_metadata.md @@ -1,37 +1,36 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: File Metadata' -canonical: "/puppet/latest/http_api/http_file_metadata.html" +title: "OpenVox Server HTTP API: File Metadata" --- -File Metadata -============= +## File Metadata -The `file_metadata` endpoint returns select metadata for a single file or many files. There are find and search variants -of the endpoint; the search variant has a trailing 's' so is actually `file_metadatas`. +The `file_metadata` endpoint returns select metadata for a single file or many files. There are find and search +variants of the endpoint; the search variant has a trailing `s`, so it is actually `file_metadatas`. -Although the term 'file' is used generically in the endpoint name and documentation, each returned item can be one of -the following three types: +Although the term 'file' is used generically in the endpoint name and documentation, each returned item can be one +of the following three types: -* File -* Directory -* Symbolic link +- File +- Directory +- Symbolic link The endpoint path includes a `:mount` which can be one of the following types: -* Custom file serving mounts as specified in fileserver.conf --- see [the docs on configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). -* `modules/` --- a semi-magical mount point which allows access to the `files` subdirectory of `` --- see [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html). -* `plugins` --- a highly magical mount point which merges the `lib` directory of every module together. Used for syncing plugins; not intended for general consumption. Per-module sub-paths can not be specified. -* `pluginfacts` --- a highly magical mount point which merges the `facts.d` directory of every module together. Used for syncing external facts; not intended for general consumption. Per-module sub-paths can not be specified. -* `tasks/` --- a semi-magical mount point which allows access to files in the `tasks` subdirectory of `` --- see the [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- Custom file serving mounts as specified in `fileserver.conf` — see the Puppet docs on + [configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). +- `modules/` — allows access to the `files` subdirectory of `` — see the Puppet docs on + [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- `plugins` — merges the `lib` directory of every module together. Used for syncing plugins; not intended for + general consumption. Per-module sub-paths cannot be specified. +- `pluginfacts` — merges the `facts.d` directory of every module together. Used for syncing external facts; not + intended for general consumption. Per-module sub-paths cannot be specified. +- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see the Puppet docs on + [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). -Note: PSON responses in the examples below are pretty-printed for readability. +## Find -Find ----- - -Get file metadata for a single file +Get file metadata for a single file. GET /puppet/v3/file_metadata/:mount/path/to/file?environment=:environment @@ -47,12 +46,17 @@ GET Optional parameters to GET: -* `links` -- either `manage` (default) or `follow`. See examples in Search below. -* `checksum_type` -- the checksum type to calculate the checksum value for the result metadata; one of `md5` (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. -* `source_permissions` -- whether (and how) Puppet should copy owner, group, and mode permissions; one of - * `ignore` (the default) will never apply the owner, group, or mode from the source when managing a file. When creating new files without explicit permissions, the permissions they receive will depend on platform-specific behavior. On POSIX, Puppet will use the umask of the user it is running as. On Windows, Puppet will use the default DACL associated with the user it is running as. - * `use` will cause Puppet to apply the owner, group, and mode from the source to any files it is managing. - * `use_when_creating` will only apply the owner, group, and mode from the source when creating a file; existing files will not have their permissions overwritten. +- `links` — either `manage` (default) or `follow`. See examples in Search below. +- `checksum_type` — the checksum type to calculate the checksum value for the result metadata; one of `md5` + (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. +- `source_permissions` — whether (and how) OpenVox should copy owner, group, and mode permissions; one of: + - `ignore` (the default) will never apply the owner, group, or mode from the source when managing a file. When + creating new files without explicit permissions, the permissions they receive depend on platform-specific + behavior. On POSIX, OpenVox uses the umask of the user it is running as. On Windows, OpenVox uses the default + DACL associated with the user it is running as. + - `use` will cause OpenVox to apply the owner, group, and mode from the source to any files it is managing. + - `use_when_creating` will only apply the owner, group, and mode from the source when creating a file; existing + files will not have their permissions overwritten. ### Example Response @@ -61,7 +65,7 @@ Optional parameters to GET: GET /puppet/v3/file_metadata/modules/example/just_a_file.txt?environment=env HTTP/1.1 200 OK - Content-Type: text/pson + Content-Type: application/json { "checksum": { @@ -83,7 +87,7 @@ Optional parameters to GET: GET /puppet/v3/file_metadata/modules/example/subdirectory?environment=env HTTP/1.1 200 OK - Content-Type: text/pson + Content-Type: application/json { "checksum": { @@ -105,7 +109,7 @@ Optional parameters to GET: GET /puppet/v3/file_metadata/modules/example/link_to_file.txt?environment=env&source_permissions=ignore HTTP/1.1 200 OK - Content-Type: text/pson + Content-Type: application/json { "checksum": { @@ -130,10 +134,9 @@ Optional parameters to GET: Not Found: Could not find file_metadata modules/example/does_not_exist -Search ------- +## Search -Get a list of metadata for multiple files +Get a list of metadata for multiple files. GET /puppet/v3/file_metadatas/foo.txt?environment=env @@ -147,14 +150,14 @@ GET ### Parameters -* `recurse` -- should always be set to `yes`; unfortunately the default is `no`, which causes a search to behave like a find operation. -* `ignore` -- file or directory regex to ignore; can be repeated. -* `links` -- either `manage` (default) or `follow`. See examples below. -* `checksum_type` -- the checksum type to calculate the checksum value for the result metadata; one of `md5` (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. -* `source_permissions` -- whether (and how) Puppet should copy owner, group, and mode permissions; one of - * `ignore` (the default) will never apply the owner, group, or mode from the source when managing a file. When creating new files without explicit permissions, the permissions they receive will depend on platform-specific behavior. On POSIX, Puppet will use the umask of the user it is running as. On Windows, Puppet will use the default DACL associated with the user it is running as. - * `use` will cause Puppet to apply the owner, group, and mode from the source to any files it is managing. - * `use_when_creating` will only apply the owner, group, and mode from the source when creating a file; existing files will not have their permissions overwritten. +- `recurse` — should always be set to `yes`; unfortunately the default is `no`, which causes a search to behave + like a find operation. +- `ignore` — file or directory regex to ignore; can be repeated. +- `links` — either `manage` (default) or `follow`. See examples below. +- `checksum_type` — the checksum type to calculate the checksum value for the result metadata; one of `md5` + (default), `md5lite`, `sha256`, `sha256lite`, `mtime`, `ctime`, and `none`. +- `source_permissions` — whether (and how) OpenVox should copy owner, group, and mode permissions; see the Find + section above for the available values and their meanings. ### Example Response @@ -163,7 +166,7 @@ GET GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=yes HTTP 200 OK - Content-Type: text/pson + Content-Type: application/json [ { @@ -238,12 +241,12 @@ GET } ] -#### Search ignoring 'sub*' and links = manage +#### Search ignoring 'sub\*' and links = manage GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=true&ignore=sub*&links=manage HTTP 200 OK - Content-Type: text/pson + Content-Type: application/json [ { @@ -290,77 +293,75 @@ GET } ] -#### Search ignoring "sub*" and links = follow +#### Search ignoring "sub\*" and links = follow -This example is identical to the above example, except for the links parameter. The resulting PSON, then, -is identical to the above example, except for: +This example is identical to the above example, except for the links parameter. The resulting JSON is identical to +the above example, except for: -* the "links" field is set to "follow" rather than "manage" in all metadata objects -* in the "link_to_file.txt" metadata: - * for "manage" the "destination" field is the link destination; for "follow", it's null - * for "manage" the "type" field is "link"; for "follow" it's "file" - * for "manage" the "mode", "owner" and "group" fields are the link's values; for "follow" the destination's values +- the `"links"` field is set to `"follow"` rather than `"manage"` in all metadata objects +- in the `"link_to_file.txt"` metadata: + - for `"manage"` the `"destination"` field is the link destination; for `"follow"`, it's null + - for `"manage"` the `"type"` field is `"link"`; for `"follow"` it's `"file"` + - for `"manage"` the `"mode"`, `"owner"`, and `"group"` fields are the link's values; for `"follow"` the + destination's values are used -~~~ -GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=true&ignore=sub*&links=follow + GET /puppet/v3/file_metadatas/modules/example?environment=env&recurse=true&ignore=sub*&links=follow -HTTP 200 OK -Content-Type: text/pson + HTTP 200 OK + Content-Type: application/json -[ - { - "checksum": { - "type": "ctime", - "value": "{ctime}2013-10-01 13:15:59 -0700" - }, - "destination": null, - "group": 20, - "links": "follow", - "mode": 493, - "owner": 501, - "path": "/etc/puppetlabs/code/modules/example/files", - "relative_path": ".", - "type": "directory" - }, - { - "checksum": { - "type": "md5", - "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" + [ + { + "checksum": { + "type": "ctime", + "value": "{ctime}2013-10-01 13:15:59 -0700" + }, + "destination": null, + "group": 20, + "links": "follow", + "mode": 493, + "owner": 501, + "path": "/etc/puppetlabs/code/modules/example/files", + "relative_path": ".", + "type": "directory" }, - "destination": null, - "group": 20, - "links": "follow", - "mode": 420, - "owner": 501, - "path": "/etc/puppetlabs/code/modules/example/files", - "relative_path": "just_a_file.txt", - "type": "file" - }, - { - "checksum": { - "type": "md5", - "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" + { + "checksum": { + "type": "md5", + "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" + }, + "destination": null, + "group": 20, + "links": "follow", + "mode": 420, + "owner": 501, + "path": "/etc/puppetlabs/code/modules/example/files", + "relative_path": "just_a_file.txt", + "type": "file" }, - "destination": null, - "group": 20, - "links": "follow", - "mode": 420, - "owner": 501, - "path": "/etc/puppetlabs/code/modules/example/files", - "relative_path": "link_to_file.txt", - "type": "file" - } -] -~~~ + { + "checksum": { + "type": "md5", + "value": "{md5}d0a10f45491acc8743bc5a82b228f89e" + }, + "destination": null, + "group": 20, + "links": "follow", + "mode": 420, + "owner": 501, + "path": "/etc/puppetlabs/code/modules/example/files", + "relative_path": "link_to_file.txt", + "type": "file" + } + ] + -Schema ------- +## Schema The file metadata response body conforms to -[the `file_metadata` schema.](../schemas/file_metadata.json) +[the `file_metadata` schema.](/openvox/latest/schemas/file_metadata.json) -Sample Module -------------- +## Sample Module The examples above use this (faux) module: diff --git a/docs/_openvox_8x/http_api/http_node.md b/docs/_openvox-server_8x/http_node.md similarity index 79% rename from docs/_openvox_8x/http_api/http_node.md rename to docs/_openvox-server_8x/http_node.md index 502c57ccc..755888e9e 100644 --- a/docs/_openvox_8x/http_api/http_node.md +++ b/docs/_openvox-server_8x/http_node.md @@ -1,28 +1,23 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Node' -canonical: "/puppet/latest/http_api/http_node.html" +title: "OpenVox Server HTTP API: Node" --- -Node -==== +## Node -The `node` endpoint is used by the puppet agent to get basic information +The `node` endpoint is used by the OpenVox agent to get basic information about a node. The returned information includes the node name and environment, and optionally any classes set by an External Node Classifier and a hash of parameters which may include the node's facts. The returned node may have a different environment from the one given in -the request if Puppet is configured with an ENC. +the request if OpenVox is configured with an ENC. -Find ----- +## Find -Retrieve data for a node +Retrieve data for a node. GET /puppet/v3/node/:certname?environment=:environment&transaction_uuid=:transaction_uuid&configured_environment=:environment - ### Supported HTTP Methods GET @@ -52,7 +47,7 @@ environment, which might differ from what the client believes is its current env < Content-Length: 4630 { - "name":"thinky.corp.puppetlabs.net", + "name":"thinky.corp.example.net", "parameters":{ "architecture":"amd64", "kernel":"Linux", @@ -65,8 +60,7 @@ environment, which might differ from what the client believes is its current env "environment":"production" } -Schema ------- +## Schema A node response body conforms to -[the node schema.](../schemas/node.json) +[the node schema.](/openvox/latest/schemas/node.json) diff --git a/docs/_openvox_8x/http_api/http_report.md b/docs/_openvox-server_8x/http_report.md similarity index 65% rename from docs/_openvox_8x/http_api/http_report.md rename to docs/_openvox-server_8x/http_report.md index e3d341543..ad354db51 100644 --- a/docs/_openvox_8x/http_api/http_report.md +++ b/docs/_openvox-server_8x/http_report.md @@ -1,24 +1,19 @@ --- layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Report' -canonical: "/puppet/latest/http_api/http_report.html" +title: "OpenVox Server HTTP API: Report" --- -Report -====== -This document describes the OpenVox Server's report endpoint and the schema for -Report Format 6 in technical term. Also see the -[documentation](https://puppet.com/docs/puppet/latest/format_report.html). +## Report -The `report` endpoint allows clients to send reports to the master via `http` -or `https`. Once received by the master they are processed by the *report -processors* configured to be triggered when a report is received. As an -example, storing reports in PuppetDB is handled by one such report processor. +This document describes the OpenVox Server report endpoint and the schema for Report Format 9. -Save ----- -The http(s) endpoint for sending reports to the master is: +The `report` endpoint allows clients to send reports to the OpenVox Server via HTTP or HTTPS. Once received by the +server they are processed by the *report processors* configured to be triggered when a report is received. For +example, storing reports in OpenVoxDB is handled by one such report processor. + +## Save + +The HTTP(S) endpoint for sending reports to the server is: PUT /puppet/v3/report/:nodename?environment=:environment @@ -36,25 +31,26 @@ None ### Content -The content of a report is typically generated by the Puppet Runtime and consists of a JSON serialization of `Puppet::Transaction::Report` object which in turn contains a structure of objects with of the following runtime types: +The content of a report is typically generated by the OpenVox agent runtime and consists of a JSON serialization of +a report object, which in turn contains a structure of objects of the following types: + +- Log entries +- Metrics +- Resource statuses +- Transaction events -* `Puppet::Util::Log` -* `Puppet::Util::Metric` -* `Puppet::Resource::Status` -* `Puppet::Transaction::Event` +This JSON serialization must comply with the endpoint's report JSON schema. -This JSON serialization is compliant with the endpoint's report JSON schema. +## Example -Example -------- -Here is an example of a PUT request. (Note that the content-length is not correct as the -example is formatted for readability) +Here is an example of a PUT request. (Note that the content-length is not correct as the example is formatted for +readability.) - PUT /puppet/v3/report/kermit.com?environment=production HTTP/1.0 + PUT /puppet/v3/report/kermit.example.com?environment=production HTTP/1.0 Content-Type: application/json Content-Length: 1428 - {"host"=>"kermit.com", + {"host"=>"kermit.example.com", "time"=>"2013-09-12T03:50:59.009301000+02:00", "configuration_version"=>1357986, "transaction_uuid"=>"df34516e-4050-402d-a166-05b03b940749", @@ -124,8 +120,7 @@ example is formatted for readability) "events"=>[]}}, "cached_catalog_status"=> "not_used"} -Schema ------- +## Schema The sent report objects must conform to -[the report schema.](../schemas/report.json) +[the report schema.](/openvox/latest/schemas/report.json) diff --git a/docs/_openvox-server_8x/pson.md b/docs/_openvox-server_8x/pson.md new file mode 100644 index 000000000..49078edac --- /dev/null +++ b/docs/_openvox-server_8x/pson.md @@ -0,0 +1,65 @@ +--- +layout: default +title: "OpenVox Server HTTP API: PSON" +--- + +PSON +==== + +> **Deprecated:** PSON support is retained for backward compatibility but should not be used in new integrations. +> All OpenVox HTTP API endpoints that previously supported PSON now prefer JSON (`application/json`). PSON remains +> an accepted fallback format for binary content that cannot be represented as valid UTF-8. + +PSON is a variant of [JSON](http://json.org) that OpenVox uses for serializing data to transmit across the network +or store on disk. Whereas JSON requires that the serialized form is valid unicode (usually UTF-8), PSON is 8-bit +ASCII, which allows it to represent arbitrary byte sequences in strings. + +OpenVox uses the MIME types `"pson"` and `"text/pson"` to refer to PSON. + +Differences from JSON +--------------------- + +PSON does *not differ* from JSON in its representation of objects, arrays, numbers, booleans, and null values. +PSON *does* serialize strings differently from JSON. + +A PSON string is a sequence of 8-bit ASCII encoded data. It must start and end with `"` (ASCII 0x22) characters. +Between these characters it may contain any byte sequence. Some individual characters are represented by a sequence +of characters: + +| Byte | ASCII Character | Encoded Sequence | Encoded ASCII Sequence | +| ---- | --------------- | ---------------- | ---------------------- | +| 0x22 | " | 0x5C, 0x22 | \" | +| 0x5c | \ | 0x5C, 0x5C | \\ | +| 0x08 | Backspace | 0x5C, 0x62 | \b | +| 0x09 | Horizontal Tab | 0x5C, 0x74 | \t | +| 0x0A | Line Feed | 0x5C, 0x6E | \n | +| 0x0C | Form Feed | 0x5C, 0x66 | \f | +| 0x0D | Carriage Return | 0x5C, 0x72 | \r | + +In addition, any character between 0x00 and 0x1F (except the ones listed above) must be encoded as a six byte +sequence of `\u` followed by four ASCII digits of the hex number of the desired character. For example the ASCII +Record Separator character (0x1E) is represented as `` (0x5C, 0x75, 0x30, 0x30, 0x31, 0x45). + +Decoding PSON Using JSON Parsers +--------------------------------- + +Many languages have JSON parsers already, which can often be used to parse PSON data. Although JSON requires that +it is encoded as unicode, most parsers will produce usable output from PSON if they are instructed to interpret the +input as Latin-1 encoding. + +In all these examples there is a file available called `data.pson` that contains the ruby structure +`{ "data" => "\x07\x08\xC3\xC3" }` encoded as PSON (the value is an invalid unicode sequence). In bytes the data +is: + + 0x7b 0x22 0x64 0x61 0x74 0x61 0x22 0x3a 0x22 0x5c 0x75 0x30 0x30 0x30 0x37 0x5c 0x62 0xc3 0xc3 0x22 0x7d + +Python Example: + + >>> import json + >>> json.load(open("data.pson"), "latin_1") + {u'data': u'\x07\x08\xc3\xc3'} + +Clojure Example: + + user> (parse-string (slurp "data.pson" :encoding "ISO-8859-1")) + {"data" "^G\bÃÃ"} diff --git a/docs/_openvox_8x/http_api/http_api_index.md b/docs/_openvox_8x/http_api/http_api_index.md deleted file mode 100644 index 61c64527e..000000000 --- a/docs/_openvox_8x/http_api/http_api_index.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'OpenVox HTTP API: Index' -canonical: "/openvox/latest/http_api/http_api_index.html" ---- - -A OpenVox master server provides several services via HTTP API, and the OpenVox -agent application uses those services to resolve a node's credentials, retrieve -a configuration catalog, retrieve file data, and submit reports. - -In general, these APIs aren't designed for use by tools other than OpenVox agent, -and they've historically relied on a lot of shared code to work correctly. -This is gradually changing, although we expect external use of these APIs to -remain low for the foreseeable future. - -OpenVox will often send garbage URL parameters, such as `fail_on_404` and -`ignore_cache`. The server will ignore any parameters it isn't expecting. - -V1/V2 HTTP APIs (Removed) ---------------- - -The V1 and V2 APIs were removed in OpenVox 4.0.0. The routes that were previously -under `/` or `/v2.0` can now be found under the [`/puppet/v3`](#puppet-v3-http-api) -API or [`/puppet-ca/v1`](#ca-v1-http-api) API. - -Starting with version 2.1, the OpenVox Server 2.x series provides both the -current and previous API endpoints, and can serve nodes running OpenVox agent 3.x -and 4.x. However, Rack masters, WEBrick masters, and OpenVox Server 2.0 cannot -serve nodes running OpenVox 3.x. - -OpenVox and OpenVox CA APIs ------------------- - -Beginning with OpenVox 4, OpenVox's HTTP API has been split into two APIs, which -are versioned separately. There is now an API for configuration-related services -and a separate one for the certificate authority (CA). - -All configuration endpoints are prefixed with `/puppet`, while all CA endpoints are -prefixed with `/puppet-ca`. All endpoints are explicitly versioned: the prefix -is always immediately followed by a string like `/v3` (a directory separator, -the letter `v`, and the version number of the API). - -### Authorization - -Authorization for `/puppet` endpoints is still controlled with OpenVox's `auth.conf` -authorization system. - -OpenVox Server ignores `auth.conf` for `/puppet-ca` endpoints. Access to the -`certificate_status` endpoint is configured in OpenVox Server's `ca.conf` file, -and the remaining CA endpoints are always accessible. Rack OpenVox master servers -still use `auth.conf` for `/puppet-ca`. - -When specifying authorization in `auth.conf`, the prefix and the version number -(e.g. `/puppet/v3`) on the paths must be retained, since Puppet matches -authorization rules against the full request path. - -OpenVox V3 HTTP API ------------------- - -The OpenVox agent application uses several network services to manage systems. -These services are all grouped under the `/puppet` API. Other tools can access -these services and use the OpenVox master's data for other purposes. - -The V3 API contains endpoints of two types: those that are based on dispatching -to OpenVox's internal "indirector" framework, and those that are not (namely the -[environment endpoints](#environment-endpoints)). - -Every HTTP endpoint that dispatches to the indirector follows the form: -`/puppet/v3/:indirection/:key?environment=:environment` where: - -* `:environment` is the name of the environment that should be in effect for - the request. Not all endpoints need an environment, but the query - parameter must always be specified. -* `:indirection` is the indirection to dispatch the request to. -* `:key` is the "key" portion of the indirection call. - -Using this API requires significant understanding of how OpenVox's internal -services are structured, but the following documents attempt to specify what is -available and how to interact with it. - -### Configuration Management Services - -These services are all directly used by the OpenVox agent application, in order -to manage the configuration of a node. - -These endpoints accept payload formats formatted as JSON or PSON (MIME types of -`application/json` and `text/pson`, respectively) except for `File Content` and -`File Bucket File` which always use `application/octet-stream`. - -* [Facts](./http_facts.md) -* [Catalog](./http_catalog.md) -* [Node](./http_node.md) -* [File Bucket File](./http_file_bucket_file.md) -* [File Content](./http_file_content.md) -* [File Metadata](./http_file_metadata.md) -* [Report](./http_report.md) - -### Informational Services - -These services are not directly used by OpenVox agent, but may be used by other -tools. - -* [Status](./http_status.md) - -### Environment Endpoints - -The endpoints with a different format are the `/puppet/v3/environments` and -the `/puppet/v3/environment/:environment` endpoints. - -These endpoints will only accept payloads formatted as JSON and respond -with JSON (MIME type of `application/json`). - -* [Environments](./http_environments.md) -* [Environment Catalog](./http_environment.md) - -### OpenVox Server-specific endpoints - -When using [Puppet Server 2.3 or newer](https://puppet.com/docs/puppetserver/2.3/) -as a OpenVox master, OpenVox Server adds additional `/puppet/v3/` endpoints: - -* [Static File Content](https://puppet.com/docs/puppetserver/latest/puppet-api/v3/static_file_content.md) -* [Environment Classes](https://puppet.com/docs/puppetserver/latest/puppet-api/v3/environment_classes.md) - -#### Error Responses - -The `environments` endpoint will respond to error conditions in a uniform manner -and use standard HTTP response code to signify those errors. - -* When the client submits a malformed request, the API will return a 400 Bad - Request response. -* When the client is not authorized, the API will return a 403 Not Authorized - response. -* When the client attempts to use an HTTP method that is not permissible for - the endpoint, the API will return a 405 Method Not Allowed response. -* When the client asks for a response in a format other than JSON, the API will - return a 406 Unacceptable response. -* When the server encounters an unexpected error during the handling of a - request, it will return a 500 Server Error response. -* When the server is unable to find an endpoint handler for an http request, - it will return a 404 Not Found response - -All error responses will contain a body, except when it is a HEAD request. The -error responses will uniformly be a JSON object with the following properties: - -* `message`: (`String`) A human readable message explaining the error. -* `issue_kind`: (`String`) A unique label to identify the error class. - -A [JSON schema for the error objects](../schemas/error.json) is also available. - -CA V1 HTTP API --------------- - -The CA API contains all of the endpoints used in support of OpenVox's PKI -system. - -The CA V1 endpoints share the same basic format as the Puppet V3 API, since -they are also based off of OpenVox's internal "indirector". However, they have -a different prefix and version. The endpoints thus follow the form: -`/puppet-ca/v1/:indirection/:key?environment=:environment` where: - -* `:environment` is an arbitrary placeholder word, required for historical - reasons. No CA endpoints actually use an environment, but the query parameter - must always be specified. -* `:indirection` is the indirection to dispatch the request to. -* `:key` is the "key" portion of the indirection call. - -As with the OpenVox V3 API, using this API requires a significant amount of -understanding of how OpenVox's internal services are structured. The following -documents provide additional specification. - -### SSL Certificate Related Services - -These endpoints only accept plain text payload formats. Historically, OpenVox has -used the MIME type `s` to mean `text/plain`. In OpenVox 5, it will always use -`text/plain`, but will continue to accept `s` to mean the same thing. - -* [Certificate](./http_certificate.md) -* [Certificate Signing Requests](./http_certificate_request.md) -* [Certificate Status](./http_certificate_status.md) -* [Certificate Revocation List](./http_certificate_revocation_list.md) - -Serialization Formats ---------------------- - -OpenVox sends messages using several different serialization formats. Not all -REST services support all of the formats. - -* [JSON](https://tools.ietf.org/html/rfc7159) -* [PSON](./pson.md) - -`YAML` was supported in earlier versions of OpenVox, but is no longer for security reasons. diff --git a/docs/_openvox_8x/http_api/http_catalog.md b/docs/_openvox_8x/http_api/http_catalog.md deleted file mode 100644 index f0ea5f0bf..000000000 --- a/docs/_openvox_8x/http_api/http_catalog.md +++ /dev/null @@ -1,376 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'OpenVox HTTP API: Catalog' -canonical: "/openvox/latest/http_api/http_catalog.html" ---- - -Catalog -============= - -The `catalog` endpoint returns a catalog for the specified node name given the provided facts. - -Find ----- - -Retrieve a catalog. - - POST /puppet/v3/catalog/:nodename - GET /puppet/v3/catalog/:nodename?environment=:environment - -### Supported HTTP Methods - -POST, GET - -### Supported Response Formats - -`application/json`, `text/pson` - -### Notes - -The POST and GET methods are functionally equivalent. Both provide the 3 parameters specified below: the POST in the -request body, the GET in the query string. - -OpenVox originally used GET; POST was added because some web servers have a maximum URI length of -1024 bytes (which is easily exceeded with the `facts` parameter). - -The examples below use the POST method. - -### Parameters - -Four parameters should be provided to the POST or GET: - -- `environment`: the environment name. -- `facts_format`: must be `application/json` or `pson`. -- `facts`: serialized JSON or PSON of the facts hash. Since facts can contain `&`, which - is also the HTTP query parameter delimiter, facts are doubly-escaped. -- `transaction_uuid`: a transaction uuid identifying the entire transaction (shows up in the report as well). - -Two optional parameters are required for static catalogs: -- `static_catalog`: a boolean requesting a -[static catalog](https://puppet.com/docs/puppet/latest/static_catalogs.html) if available; should always -be `true`. -- `checksum_type`: a dot-separated list of checksum types supported by the agent, for use in file resources of a static -catalog. The order signifies preference, highest first. - -Optional parameters that may be provided to the POST or GET: - -- `configured_environment`: the environment configured on the client. May be - provided to notify an ENC that the client requested a specific environment - which might differ from what the client believes is its current environment. -- `job_id`: which orchestration job triggered this catalog request. - -### Example Response - -#### Catalog found - - POST /puppet/v3/catalog/elmo.mydomain.com - - environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%257B%2522name%2522%253A%2522elmo.mydomain.com%2522%252C%2522values%2522%253A%257B%2522architecture%2522%253A%2522x86_64%2522%257D%257D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c - - HTTP 200 OK - Content-Type: application/json - - { - "tags": [ - "settings", - "multi_param_class", - "class" - ], - "name": "elmo.mydomain.com", - "version": 1377473054, - "code_id": null, - "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e", - "catalog_format": 1, - "environment": "production", - "resources": [ - { - "type": "Stage", - "title": "main", - "tags": [ - "stage" - ], - "exported": false, - "parameters": { - "name": "main" - } - }, - { - "type": "Class", - "title": "Settings", - "tags": [ - "class", - "settings" - ], - "exported": false - }, - { - "type": "Class", - "title": "main", - "tags": [ - "class" - ], - "exported": false, - "parameters": { - "name": "main" - } - }, - { - "type": "Class", - "title": "Multi_param_class", - "tags": [ - "class", - "multi_param_class" - ], - "line": 10, - "exported": false, - "parameters": { - "one": "hello", - "two": "world" - } - }, - { - "type": "Notify", - "title": "foo", - "tags": [ - "notify", - "foo", - "class", - "multi_param_class" - ], - "line": 4, - "exported": false, - "parameters": { - "message": "One is hello, two is world" - } - } - ], - "edges": [ - { - "source": "Stage[main]", - "target": "Class[Settings]" - }, - { - "source": "Stage[main]", - "target": "Class[main]" - }, - { - "source": "Stage[main]", - "target": "Class[Multi_param_class]" - }, - { - "source": "Class[Multi_param_class]", - "target": "Notify[foo]" - } - ], - "classes": [ - "settings", - "multi_param_class" - ] - } - -#### Static Catalog found - -~~~ -POST /puppet/v3/catalog/elmo.mydomain.com - -environment=env&configured_environment=canary_env&facts_format=application%2Fjson&facts=%7B%22name%22%3A%22elmo.mydomain.com%22%2C%22values%22%3A%7B%22architecture%22%3A%22x86_64%22%7D&transaction_uuid=aff261a2-1a34-4647-8c20-ff662ec11c4c&static_catalog=true&checksum_type=sha256.md5 - -HTTP 200 OK -Content-Type: application/json - -{ - "tags": [ - "settings", - "multi_param_class", - "class" - ], - "name": "elmo.mydomain.com", - "version": 1377473054, - "code_id": "arbitrary_code_id_string", - "catalog_uuid": "827a74c8-cf98-44da-9ff7-18c5e4bee41e", - "catalog_format": 1, - "environment": "production", - "resources": [ - { - "type": "Stage", - "title": "main", - "tags": [ - "stage" - ], - "exported": false, - "parameters": { - "name": "main" - } - }, - { - "type": "Class", - "title": "Settings", - "tags": [ - "class", - "settings" - ], - "exported": false - }, - { - "type": "Class", - "title": "main", - "tags": [ - "class" - ], - "exported": false, - "parameters": { - "name": "main" - } - }, - { - "type": "Class", - "title": "Multi_param_class", - "tags": [ - "class", - "multi_param_class" - ], - "line": 10, - "exported": false, - "parameters": { - "one": "hello", - "two": "world" - } - }, - { - "type": "Notify", - "title": "foo", - "tags": [ - "notify", - "foo", - "class", - "multi_param_class" - ], - "line": 4, - "exported": false, - "parameters": { - "message": "One is hello, two is world" - } - }, - { - "type": "File", - "title": "/tmp/foo", - "tags": [ - "file", - "class" - ], - "line": 12, - "exported": false, - "parameters": { - "ensure": "file", - "source": "puppet:///modules/a_module/foo" - } - }, - { - "type": "File", - "title": "/tmp/bar", - "tags": [ - "file", - "class" - ], - "line": 16, - "exported": false, - "parameters": { - "ensure": "present", - "source": "puppet:///modules/a_module/bar", - "recurse", "true" - } - ], - "edges": [ - { - "source": "Stage[main]", - "target": "Class[Settings]" - }, - { - "source": "Stage[main]", - "target": "Class[main]" - }, - { - "source": "Stage[main]", - "target": "Class[Multi_param_class]" - }, - { - "source": "Class[Multi_param_class]", - "target": "Notify[foo]" - }, - { - "source": "Class[Main]", - "target": "File[/tmp/foo]" - } - ], - "classes": [ - "settings", - "multi_param_class" - ] - "metadata": { - "/tmp/foo": { - "checksum": { - "type": "sha256", - "value": "{sha256}5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03" - }, - "content_uri": "puppet:///modules/a_module/files/foo", - "destination": null, - "group": 20, - "links": "manage", - "mode": 420, - "owner": 501, - "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/foo.txt", - "relative_path": null, - "source": "puppet:///modules/a_module/foo", - "type": "file" - } - }, - "recursive_metadata": { - "/tmp/bar": { - "puppet:///modules/a_module/bar": [ - { - "checksum": { - "type": "ctime", - "value": "{ctime}2016-02-19 17:38:36 -0800" - }, - "content_uri": "puppet:///modules/a_module/files/bar", - "destination": null, - "group": 20, - "links": "manage", - "mode": 420, - "owner": 501, - "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/bar", - "relative_path": ".", - "source": null, - "type": "directory" - }, - { - "checksum": { - "type": "sha256", - "value": "{sha256}962dbd7362c34a20baac8afd13fba734d3d51cc2944477d96ee05a730e5edcb7" - }, - "content_uri": "puppet:///modules/a_module/files/bar/baz", - "destination": null, - "group": 20, - "links": "manage", - "mode": 420, - "owner": 501, - "path": "/etc/puppetlabs/code/environments/production/modules/a_module/files/bar", - "relative_path": "baz", - "source": null, - "type": "file" - } - ] - } - } -} -~~~ - -Schema ------- - -In the POST request body (or the GET query), the facts parameter should conform -to [the facts schema.](../schemas/facts.json) - -A catalog response body conforms to -[the catalog schema.](../schemas/catalog.json) diff --git a/docs/_openvox_8x/http_api/http_certificate.md b/docs/_openvox_8x/http_api/http_certificate.md deleted file mode 100644 index be67b5cf9..000000000 --- a/docs/_openvox_8x/http_api/http_certificate.md +++ /dev/null @@ -1,115 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Certificate' -canonical: "/puppet/latest/http_api/http_certificate.html" ---- - -Certificate -============= - -The `certificate` endpoint returns the certificate for the specified name, -which might be either a standard certname or `ca`. - -Under Puppet Server's CA service, the `environment` parameter is ignored and can -be omitted. Under a Rack or WEBrick OpenVox Server, `environment` is required and -must be a valid environment, but it has no effect on the response. - -Find ----- - -Get a certificate. - - GET /puppet-ca/v1/certificate/:nodename?environment=:environment - - -### Supported HTTP Methods - -GET - -### Supported Response Formats - -`text/plain` - -The returned certificate is always in the `.pem` format. - -### Parameters - -None - -### Responses - -#### Certificate found - - GET /puppet-ca/v1/certificate/elmo.mydomain.com?environment=env - - HTTP 200 OK - Content-Type: text/plain - - -----BEGIN CERTIFICATE----- - MIIFujCCA6KgAwIBAgIBATANBgkqhkiG9w0BAQsFADBiMWAwXgYDVQQDDFdQdXBw - ZXQgQ0EgZ2VuZXJhdGVkIG9uIGRoY3A1MC5reWxvLmJhY2tsaW5lLnB1cHBldGxh - YnMubmV0IGF0IDIwMTMtMDYtMjQgMTY6MzA6MTcgLTA3MDAwHhcNMTMwNjIzMjMz - MDE5WhcNMTgwNjIzMjMzMDE5WjBiMWAwXgYDVQQDDFdQdXBwZXQgQ0EgZ2VuZXJh - dGVkIG9uIGRoY3A1MC5reWxvLmJhY2tsaW5lLnB1cHBldGxhYnMubmV0IGF0IDIw - MTMtMDYtMjQgMTY6MzA6MTcgLTA3MDAwggIiMA0GCSqGSIb3DQEBAQUAA4ICDwAw - ggIKAoICAQDABq1lmzccjuRmnCdXvTmdeXJGb9S8r8+I+G6fkHTa1WKDSob9PZpS - eXJtanbl0zNws9yBt1Dko2zhKDKctBRWf5CT42nDxBZPY7SaD7KaCzb07g9wfWgU - BOb/6smyl/iySEmQzzFLRgZbo5A9WLiy/UdyQim1faakevRme2Xi/l/i0TKbpu27 - DhCS+E8aC8Bvaj0ph0T+TzYphTR76pP5Kps6G7Jyk/HFYrVXnY44X2PEt2mgkEXp - xHCbU+qCFMtTLMG+ZArA/noM3I/O6W5LhLSzApjut/M7UdMlpZ45PGDrsvf2R306 - NcOh+zbbkhxuIaGqaxeaenYzbOlA3gXhZvYaV6EKjXNtm7BslpsvhLi0U+CWyb3C - qRkpex0MgxJgxoqViJ4TDVA+EmztOnK86+G4HGeJqTPQloYO/Td1wMT1Txh9T5Ue - Wctw/g+4o22EyJQRo+vxxzHNRIfe7EHAerMUtLT5u9MJeQb9N1iUR2ATNAN+QiB2 - KEqyc9eMapK6QUZFV23Xvbdup1WCrgsWXBqyRWKV7x0sc9Wv8RMRKEFYaBeHEVXU - m0hGgF34Z8Rzphq2H1FjkLD+xbtGOjrA1Mb2De81Hfvrf18497X5UMPtsuzOt/XU - PHbbSCy+05J7VNZ/gaiGqgpHfcG5yiqCdj1LIzhFuuvm+fADPxK38wIDAQABo3sw - eTA3BglghkgBhvhCAQ0EKhYoUHVwcGV0IFJ1YnkvT3BlblNTTCBJbnRlcm5hbCBD - ZXJ0aWZpY2F0ZTAOBgNVHQ8BAf8EBAMCAQYwDwYDVR0TAQH/BAUwAwEB/zAdBgNV - HQ4EFgQUEhn/MqSDtuxg12klWosCGenxf1cwDQYJKoZIhvcNAQELBQADggIBAH1G - L3FG/keKlGqs70PxxvR1wCo4VM3K/C+5uxnzm1MHEAd96nhtwE6YSkUe+XgDiXfC - +NXS2C4TeTQAEo6grREapWDjhJvrhrgqTZmb4lTKzb91II3/VGYzG5UXxID262zy - QLoX/IBN/xDJ5ds0wF2adUbnHUssEGGljgngewH/7kjeW/L5iL+USXZnKHPSggjM - RAEjlucE/rDqDNoxhOS4K2PjseFm7krW4cZ0gNmxdrhc7OhmJ56dH92F4M9jn7Qy - EqxWB304U/aMcO3NJxTQc7AreL/pUtjtI6hxM4miHbjSh6RfNBqhzRyJvxA6gc6g - m3kumdw04KZFSs/6fPFFbI60i5K+vioB4CnUWpj+3Z+OnDEvhQJEACR1JC8A67Ih - x+GDlbHLU1BWonwZzSMJz+ABXV3dwIrOSFHI0UmDXg+cIdZ+SaL93qMjUVU4v9nu - gR9yJGMqNuzLjgfbD/KGCEEAITKBwPvCVd//OMlWVrXr7vvt+yo6STIlTJxABJDp - CSLyHUtT++CsPXsPADxgRctpIbh1eMFEivkK9Oy+W/CZYIZnARVysUpMWg7TkXqx - mSCXy9ZXLWqU/ssVhbLS9vFVa5pvxcyfiRpsFg0XZsx8mnZP6OaWcL8FjF+/NwNP - tg1+DuYTn+d54OHi/GZEnvutgrDZyrJDrrb/Czm9 - -----END CERTIFICATE----- - -#### Certificate not found - - GET /puppet-ca/v1/certificate/certificate_does_not_exist?environment=env - - HTTP 404 Not Found - Content-Type: text/plain - - Not Found: Could not find certificate certificate_does_not_exist - -#### No Certificate name given - - GET /puppet-ca/v1/certificate?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /puppet-ca/v1/certificate - -#### Master is not a CA - - GET /puppet/v1/certificate/valid_certificate?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - this master is not a CA - - -Schema ------- - -A `certificate` response body is not structured data according to any standard scheme such as -json/pson/yaml, so no schema is applicable. diff --git a/docs/_openvox_8x/http_api/http_certificate_request.md b/docs/_openvox_8x/http_api/http_certificate_request.md deleted file mode 100644 index d6abbe538..000000000 --- a/docs/_openvox_8x/http_api/http_certificate_request.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Certificate Request' -canonical: "/puppet/latest/http_api/http_certificate_request.html" ---- - -Certificate Request -============= - -The `certificate_request` endpoint submits a Certificate Signing Request (CSR) -to the master. The master must be configured to be a CA. The returned -CSR is always in the `.pem` format. - -Under Puppet Server's CA service, the `environment` parameter is ignored and can -be omitted. Under a Rack or WEBrick OpenVox Server, `environment` is required and -must be a valid environment, but it has no effect on the response. - -Find ----- - -Get a submitted CSR - - GET /puppet-ca/v1/certificate_request/:nodename?environment=:environment - Accept: text/plain - -Save ----- - -Submit a CSR - - PUT /puppet-ca/v1/certificate_request/:nodename?environment=:environment - Content-Type: text/plain - -Note: The `:nodename` must match the Common Name on the submitted CSR. - -Note: Although the `Content-Type` is sent as `text/plain` the content is -specifically a CSR in PEM format. - -Search ----- - -**Note:** The plural `certificate_requests` endpoint is a legacy feature. Puppet -Server doesn't support it, and we don't plan to add support in the future. - -List submitted CSRs - - GET /puppet-ca/v1/certificate_requests/:ignored_pattern?environment=:environment - Accept: text/plain - -The `:ignored_pattern` parameter is not used, but must still be provided. - -Destroy ----- - -Delete a submitted CSR - - DELETE /puppet-ca/v1/certificate_request/:nodename?environment=:environment - Accept: text/plain - -### Supported HTTP Methods - -The default configuration only allows requests that result in a Find and a -Save. You need to modify auth.conf in order to allow clients to use Search and -Destroy actions. It is not recommended that you change the default settings. - -GET, PUT, DELETE - -### Supported Response Formats - -`text/plain` - -The returned CSR is always in the `.pem` format. - -### Parameters - -None - -### Examples - -#### CSR found - - GET /puppet-ca/v1/certificate_request/agency?environment=env - - HTTP/1.1 200 OK - Content-Type: text/plain - - -----BEGIN CERTIFICATE REQUEST----- - MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G - A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx - DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr - FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W - kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV - LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD - gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j - O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS - ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0= - -----END CERTIFICATE REQUEST----- - -#### CSR not found - - GET /puppet-ca/v1/certificate_request/does_not_exist?environment=env - - HTTP/1.1 404 Not Found - Content-Type: text/plain - - Not Found: Could not find certificate_request does_not_exist - -#### No node name given - - GET /puppet-ca/v1/certificate_request?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /puppet-ca/v1/certificate_request - -#### Delete a CSR that exists - - DELETE /puppet-ca/v1/certificate_request/agency?environment=production - Accept: s - - HTTP/1.1 200 OK - Content-Type: text/plain - - 1 - -#### Delete a CSR that does not exists - - DELETE /puppet-ca/v1/certificate_request/missing?environment=production - Accept: s - - HTTP/1.1 200 OK - Content-Type: text/plain - - false - -#### Retrieve all CSRs - - GET /puppet-ca/v1/certificate_requests/ignored?environment=production - Accept: s - - HTTP/1.1 200 OK - Content-Type: text/plain - - -----BEGIN CERTIFICATE REQUEST----- - MIIBnzCCAQwCAQAwYzELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G - A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx - DzANBgNVBAMTBmFnZW5jeTCBnzANBgkqhkiG9w0BAQEFAAOBjQAwgYkCgYEAxSCr - FKUKjVGFPuQ0iGM9mZKw94sOIgGohqrHH743kPvjsId3d38Qk+H+1DbVf42bQY0W - kAVcwNDqmBnx0lOtQ0oeGnbbwlJFjhqXr8jFEljPrc9S2/IIILDf/FeYWw9lRiOV - LoU6ZfCIBfq6v4D4KX3utRbOoELNyBeT6VA1ufMCAwEAAaAAMAkGBSsOAwIPBQAD - gYEAno7O1jkR56TNMe1Cw/eyQUIaniG22+0kmoftjlcMYZ/IKCOz+HRgnDtBPf8j - O5nt0PQN8YClW7Xx2U8ZTvBXn/UEKMtCBkbF+SULiayxPgfyKy/axinfutEChnHS - ZtUMUBLlh+gGFqOuH69979SJ2QmQC6FNomTkYI7FOHD/TG0= - -----END CERTIFICATE REQUEST----- - - --- - -----BEGIN CERTIFICATE REQUEST----- - MIIBnjCCAQsCAQAwYjELMAkGA1UEBhMCVUsxDzANBgNVBAgTBkxvbmRvbjEPMA0G - A1UEBxMGTG9uZG9uMSEwHwYDVQQKExhJbnRlcm5ldCBXaWRnaXRzIFB0eSBMdGQx - DjAMBgNVBAMTBWFnZW50MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC1tucK - enT1CkDPgsCU/0e2cbzRsiKF8yHH7+ntF6Q3d9ZCaZWJ00mj0+YmiYrnum+KAikE - 45Iaf9vaUV3CPsDVrUPOI8kYehiv868ZhP3nxblE6iuNBK+Fdv9GN/vKQrmL5iRE - bIrOM3/lxpS7SpidGdA6EIVlS3604bwLY4xHNQIDAQABoAAwCQYFKw4DAg8FAAOB - gQAXH0YFuidPqB6P2MyPEEGZ3rzozINBx/oXvGptXI60Zy5mgH6iAkrZfi57pEzP - jFoO2JRaFxTJC1FVpc4zR1K6sq4h3fIMwqppJRX+5wJNKyhU61eY2gR2O/rAJzw4 - wcUKf9JhoE7/p1cUulIIIq7t/ibCvf0LYSFwGqTwGqN2TQ== - -----END CERTIFICATE REQUEST----- - -The CSR PEMs are separated by "\n---\n" - -Schema ------- - -A `certificate_request` response body is not structured data according to any -standard scheme such as json/pson/yaml, so no schema is applicable. diff --git a/docs/_openvox_8x/http_api/http_certificate_revocation_list.md b/docs/_openvox_8x/http_api/http_certificate_revocation_list.md deleted file mode 100644 index 78689bc3e..000000000 --- a/docs/_openvox_8x/http_api/http_certificate_revocation_list.md +++ /dev/null @@ -1,200 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Certificate Revocation List' -canonical: "/puppet/latest/http_api/http_certificate_revocation_list.html" ---- - -Certificate Revocation List -=========================== - -The `certificate_revocation_list` endpoint retrieves a Certificate Revocation List (CRL) -from the master. The master must be configured to be a CA. The returned -CRL is always in the `.pem` format. - -Under Puppet Server's CA service, the `environment` parameter is ignored and can -be omitted. Under a Rack or WEBrick OpenVox Server, `environment` is required and -must be a valid environment, but it has no effect on the response. - -The `:nodename` should always be `ca`, due to the default auth.conf rules for -WEBrick and Rack OpenVox Servers. (You can use a different `:nodename` if you -change the auth rules, but it will have no effect on the response.) - -Find ----- - -Get the submitted CRL - - GET /puppet-ca/v1/certificate_revocation_list/:nodename?environment=:environment - Accept: text/plain - -### Supported HTTP Methods - -GET - -### Supported Response Formats - -`text/plain` - -The returned CRL is always in the `.pem` format. - -### Parameters - -None - -### Examples - -Since the returned CRL always looks similar to the human eye, the successful examples are each followed by an openssl -decoding of the CRL PEM file. - -#### Empty revocation list - - GET /puppet-ca/v1/certificate_revocation_list/ca?environment=env - - HTTP/1.1 200 OK - Content-Type: text/plain - - -----BEGIN X509 CRL----- - MIICdzBhAgEBMA0GCSqGSIb3DQEBBQUAMB8xHTAbBgNVBAMMFFB1cHBldCBDQTog - bG9jYWxob3N0Fw0xMzA3MTYyMDQ4NDJaFw0xODA3MTUyMDQ4NDNaoA4wDDAKBgNV - HRQEAwIBADANBgkqhkiG9w0BAQUFAAOCAgEAqyBJOy3dtCOcrb0Fu7ZOOiDQnarg - IzXUV/ug1dauPEVyURLNNr+CJrr89QZnU/71lqgpWTN/J47mO/lffMSPjmINE+ng - XzOffm0qCG2+gNyaOBOdEmQTLdHPIXvcm7T+wEqc7XFW2tjEdpEubZgweruU/+DB - RX6/PhFbalQ0bKcMeFLzLAD4mmtBaQCJISmUUFWx1pyCS6pgBtQ1bNy3PJPN2PNW - YpDf3DNZ16vrAJ4a4SzXLXCoONw0MGxZcS6/hctJ75Vz+dTMrArKwckytWgQS/5e - c/1/wlMZn4xlho+EcIPMPfCB5hW1qzGU2WjUakTVxzF4goamnfFuKbHKEoXVOo9C - 3dEQ9un4Uyd1xHxj8WvQck79In5/S2l9hdqp4eud4BaYB6tNRKxlUntSCvCNriR2 - wrDNsMuQ5+KJReG51vM0OzzKmlScgIHaqbVeNFZI9X6TpsO2bLEZX2xyqKw4xrre - OIEZRoJrmX3VQ/4u9hj14Qbt72/khYo6z/Fckc5zVD+dW4fjP2ztVTSPzBqIK3+H - zAgewYW6cJ6Aan8GSl3IfRqj6WlOubWj8Gr1U0dOE7SkBX6w/X61uqsHrOyg/E/Z - 0Wcz/V+W5iZxa4Spm0x4sfpNzf/bNmjTe4M2MXyn/hXx5MdHf/HZdhOs/lzwKUGL - kEwcy38d6hYtUjs= - -----END X509 CRL----- - - > openssl crl -inform PEM -in empty.crl -text -noout - Certificate Revocation List (CRL): - Version 2 (0x1) - Signature Algorithm: sha1WithRSAEncryption - Issuer: /CN=Puppet CA: localhost - Last Update: Jul 16 20:48:42 2013 GMT - Next Update: Jul 15 20:48:43 2018 GMT - CRL extensions: - X509v3 CRL Number: - 0 - No Revoked Certificates. - Signature Algorithm: sha1WithRSAEncryption - ab:20:49:3b:2d:dd:b4:23:9c:ad:bd:05:bb:b6:4e:3a:20:d0: - 9d:aa:e0:23:35:d4:57:fb:a0:d5:d6:ae:3c:45:72:51:12:cd: - 36:bf:82:26:ba:fc:f5:06:67:53:fe:f5:96:a8:29:59:33:7f: - 27:8e:e6:3b:f9:5f:7c:c4:8f:8e:62:0d:13:e9:e0:5f:33:9f: - 7e:6d:2a:08:6d:be:80:dc:9a:38:13:9d:12:64:13:2d:d1:cf: - 21:7b:dc:9b:b4:fe:c0:4a:9c:ed:71:56:da:d8:c4:76:91:2e: - 6d:98:30:7a:bb:94:ff:e0:c1:45:7e:bf:3e:11:5b:6a:54:34: - 6c:a7:0c:78:52:f3:2c:00:f8:9a:6b:41:69:00:89:21:29:94: - 50:55:b1:d6:9c:82:4b:aa:60:06:d4:35:6c:dc:b7:3c:93:cd: - d8:f3:56:62:90:df:dc:33:59:d7:ab:eb:00:9e:1a:e1:2c:d7: - 2d:70:a8:38:dc:34:30:6c:59:71:2e:bf:85:cb:49:ef:95:73: - f9:d4:cc:ac:0a:ca:c1:c9:32:b5:68:10:4b:fe:5e:73:fd:7f: - c2:53:19:9f:8c:65:86:8f:84:70:83:cc:3d:f0:81:e6:15:b5: - ab:31:94:d9:68:d4:6a:44:d5:c7:31:78:82:86:a6:9d:f1:6e: - 29:b1:ca:12:85:d5:3a:8f:42:dd:d1:10:f6:e9:f8:53:27:75: - c4:7c:63:f1:6b:d0:72:4e:fd:22:7e:7f:4b:69:7d:85:da:a9: - e1:eb:9d:e0:16:98:07:ab:4d:44:ac:65:52:7b:52:0a:f0:8d: - ae:24:76:c2:b0:cd:b0:cb:90:e7:e2:89:45:e1:b9:d6:f3:34: - 3b:3c:ca:9a:54:9c:80:81:da:a9:b5:5e:34:56:48:f5:7e:93: - a6:c3:b6:6c:b1:19:5f:6c:72:a8:ac:38:c6:ba:de:38:81:19: - 46:82:6b:99:7d:d5:43:fe:2e:f6:18:f5:e1:06:ed:ef:6f:e4: - 85:8a:3a:cf:f1:5c:91:ce:73:54:3f:9d:5b:87:e3:3f:6c:ed: - 55:34:8f:cc:1a:88:2b:7f:87:cc:08:1e:c1:85:ba:70:9e:80: - 6a:7f:06:4a:5d:c8:7d:1a:a3:e9:69:4e:b9:b5:a3:f0:6a:f5: - 53:47:4e:13:b4:a4:05:7e:b0:fd:7e:b5:ba:ab:07:ac:ec:a0: - fc:4f:d9:d1:67:33:fd:5f:96:e6:26:71:6b:84:a9:9b:4c:78: - b1:fa:4d:cd:ff:db:36:68:d3:7b:83:36:31:7c:a7:fe:15:f1: - e4:c7:47:7f:f1:d9:76:13:ac:fe:5c:f0:29:41:8b:90:4c:1c: - cb:7f:1d:ea:16:2d:52:3b - -#### One-item revocation list - - GET /puppet-ca/v1/certificate_revocation_list/ca?environment=env - - HTTP/1.1 200 OK - Content-Type: text/plain - - -----BEGIN X509 CRL----- - MIICnDCBhQIBATANBgkqhkiG9w0BAQUFADAfMR0wGwYDVQQDDBRQdXBwZXQgQ0E6 - IGxvY2FsaG9zdBcNMTMxMDA3MTk0ODQwWhcNMTgxMDA2MTk0ODQxWjAiMCACAQUX - DTEzMTAwNzE5NDg0MVowDDAKBgNVHRUEAwoBAaAOMAwwCgYDVR0UBAMCAQEwDQYJ - KoZIhvcNAQEFBQADggIBALrh49WNdmrJOPCRntD1nxCObmqZgl8ZwTv7TO9VkmCG - Ksvo8zR2aTIOH9VUKqWrE0squhtFJXl8dxL4PR1RiLbmhO7dp+NHdu8ejTQpoOTp - h69xbQFT3oHcIdn2cBGrLJQcZgXsiswT0KJ8nuw6eDO93yXDrguSUdou99M99wTw - 2nn1kUQKW9b0vUI7t2ADF5U8/DES+1IrvBq2IEHmg4+ekZRCxeJMuqd1R13gymcJ - osSPbRgIjCli6zD3aK4Nq5OMMpVLV/VVPwyQb4GwW4Wj5iyNAp8d/EAqtZ21ZHUi - nvuXmRtUWHJwfi40D5T2GQXxuUjB4pnh8cFq7f89iUvqoCwFo7nRIacrrweNFMYD - GxVJVMfz4PkP66ckIPQ5Uuey92dg5p2w4b2cp8NstxMdgcc3KAF483ItKA8uIDuU - 1dbzw1v2k5qUjoImueHwKolbLmPyYmvFp7hbnV+WpFbvGjyIfW3BMankDEv4ig0L - MCw6n2GKv1hSWM6Mrk8Ja1yYOFLsjI0RoVCZsf1iNiRT28haldXVTPyNtct9mGAv - 6az5W/nyixIPrrHubTx28zhmuHZx6y3hQMCLmuYOT+e7F/eFsYXVEjuJjxjr33uA - O/ii4EkTls1gzvonOtoBoGElzQAogrZI3HXCwFYvU2whLKr9cwv5bpRkUfPCMQ4n - -----END X509 CRL----- - - > openssl crl -inform PEM -in 1revoked.crl -text -noout - Certificate Revocation List (CRL): - Version 2 (0x1) - Signature Algorithm: sha1WithRSAEncryption - Issuer: /CN=Puppet CA: localhost - Last Update: Oct 7 19:48:40 2013 GMT - Next Update: Oct 6 19:48:41 2018 GMT - CRL extensions: - X509v3 CRL Number: - 1 - Revoked Certificates: - Serial Number: 05 - Revocation Date: Oct 7 19:48:41 2013 GMT - CRL entry extensions: - X509v3 CRL Reason Code: - Key Compromise - Signature Algorithm: sha1WithRSAEncryption - ba:e1:e3:d5:8d:76:6a:c9:38:f0:91:9e:d0:f5:9f:10:8e:6e: - 6a:99:82:5f:19:c1:3b:fb:4c:ef:55:92:60:86:2a:cb:e8:f3: - 34:76:69:32:0e:1f:d5:54:2a:a5:ab:13:4b:2a:ba:1b:45:25: - 79:7c:77:12:f8:3d:1d:51:88:b6:e6:84:ee:dd:a7:e3:47:76: - ef:1e:8d:34:29:a0:e4:e9:87:af:71:6d:01:53:de:81:dc:21: - d9:f6:70:11:ab:2c:94:1c:66:05:ec:8a:cc:13:d0:a2:7c:9e: - ec:3a:78:33:bd:df:25:c3:ae:0b:92:51:da:2e:f7:d3:3d:f7: - 04:f0:da:79:f5:91:44:0a:5b:d6:f4:bd:42:3b:b7:60:03:17: - 95:3c:fc:31:12:fb:52:2b:bc:1a:b6:20:41:e6:83:8f:9e:91: - 94:42:c5:e2:4c:ba:a7:75:47:5d:e0:ca:67:09:a2:c4:8f:6d: - 18:08:8c:29:62:eb:30:f7:68:ae:0d:ab:93:8c:32:95:4b:57: - f5:55:3f:0c:90:6f:81:b0:5b:85:a3:e6:2c:8d:02:9f:1d:fc: - 40:2a:b5:9d:b5:64:75:22:9e:fb:97:99:1b:54:58:72:70:7e: - 2e:34:0f:94:f6:19:05:f1:b9:48:c1:e2:99:e1:f1:c1:6a:ed: - ff:3d:89:4b:ea:a0:2c:05:a3:b9:d1:21:a7:2b:af:07:8d:14: - c6:03:1b:15:49:54:c7:f3:e0:f9:0f:eb:a7:24:20:f4:39:52: - e7:b2:f7:67:60:e6:9d:b0:e1:bd:9c:a7:c3:6c:b7:13:1d:81: - c7:37:28:01:78:f3:72:2d:28:0f:2e:20:3b:94:d5:d6:f3:c3: - 5b:f6:93:9a:94:8e:82:26:b9:e1:f0:2a:89:5b:2e:63:f2:62: - 6b:c5:a7:b8:5b:9d:5f:96:a4:56:ef:1a:3c:88:7d:6d:c1:31: - a9:e4:0c:4b:f8:8a:0d:0b:30:2c:3a:9f:61:8a:bf:58:52:58: - ce:8c:ae:4f:09:6b:5c:98:38:52:ec:8c:8d:11:a1:50:99:b1: - fd:62:36:24:53:db:c8:5a:95:d5:d5:4c:fc:8d:b5:cb:7d:98: - 60:2f:e9:ac:f9:5b:f9:f2:8b:12:0f:ae:b1:ee:6d:3c:76:f3: - 38:66:b8:76:71:eb:2d:e1:40:c0:8b:9a:e6:0e:4f:e7:bb:17: - f7:85:b1:85:d5:12:3b:89:8f:18:eb:df:7b:80:3b:f8:a2:e0: - 49:13:96:cd:60:ce:fa:27:3a:da:01:a0:61:25:cd:00:28:82: - b6:48:dc:75:c2:c0:56:2f:53:6c:21:2c:aa:fd:73:0b:f9:6e: - 94:64:51:f3:c2:31:0e:27 - -#### No node name given - - GET /puppet-ca/v1/certificate_revocation_list?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /puppet-ca/v1/certificate_revocation_list - -Schema ------- - -A `certificate_revocation_list` response body is not structured data according to any -standard scheme such as json/pson/yaml, so no schema is applicable. diff --git a/docs/_openvox_8x/http_api/http_certificate_status.md b/docs/_openvox_8x/http_api/http_certificate_status.md deleted file mode 100644 index a6988e1e4..000000000 --- a/docs/_openvox_8x/http_api/http_certificate_status.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Certificate Status' -canonical: "/puppet/latest/http_api/http_certificate_status.html" ---- - -Certificate Status -=============== - -The `certificate status` endpoint allows a client to read or alter the -status of a certificate or pending certificate request. It is only -useful on the CA. - -Under Puppet Server's CA service, the `environment` parameter is ignored and can -be omitted. Under a Rack or WEBrick OpenVox Server, `environment` is required and -must be a valid environment, but it has no effect on the response. - -Find ----- - - GET /puppet-ca/v1/certificate_status/:certname?environment=:environment - Accept: application/json, text/pson - -Retrieve information about the specified certificate. Similar to `puppetserver -ca list --certname :certname`. - -Search ------ - - GET /puppet-ca/v1/certificate_statuses/:any_key?environment=:environment - Accept: application/json, text/pson - -Retrieve information about all known certificates. Similar to `puppetserver -ca list --all`. A key is required but is ignored. - -Save ----- - - PUT /puppet-ca/v1/certificate_status/:certname?environment=:environment - Content-Type: text/pson - -Change the status of the specified certificate. The desired state -is sent in the body of the PUT request as a one-item PSON hash; the two -allowed complete hashes are `{"desired_state":"signed"}` (for signing a -certificate signing request; similar to `puppetserver ca sign`) and -`{"desired_state":"revoked"}` (for revoking a certificate; similar to -`puppetserver ca revoke`). - -Note that revoking a certificate will not clean up other info about the -host - see the DELETE request for more information. - -Delete ------ - - DELETE /puppet-ca/v1/certificate_status/:hostname?environment=:environment - Accept: application/json, text/pson - -Cause the certificate authority to discard all SSL information regarding -a host (including any certificates, certificate requests, and keys). -This does not revoke the certificate if one is present; if you wish to -emulate the behavior of `puppetserver ca clean`, you must PUT a -`desired_state` of `revoked` before deleting the host’s SSL information. - -If the deletion was successful, it returns a string listing the deleted -classes like - - "Deleted for myhost: Puppet::SSL::Certificate, Puppet::SSL::Key" - -Otherwise it returns - - "Nothing was deleted" - -### Supported HTTP Methods - -This endpoint is disabled in the default configuration. It is -recommended to be careful with this endpoint, as it can allow control -over the certificates used by the OpenVox Server. - -GET, PUT, DELETE - - -### Supported Response Formats - -`application/json`, `text/pson`, `pson` - -This endpoint can produce yaml as well, but the returned data is -incomplete. - -### Examples - -#### Certificate information - - GET /puppet-ca/v1/certificate_status/mycertname?environment=env - - HTTP/1.1 200 OK - Content-Type: text/pson - - { - "name":"mycertname", - "state":"signed", - "fingerprint":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F", - "fingerprints":{ - "default":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F", - "SHA1":"77:E6:5A:7E:DD:83:78:DC:F8:51:E3:8B:12:71:F4:57:F1:C2:34:AE", - "SHA256":"A6:44:08:A6:38:62:88:5B:32:97:20:49:8A:4A:4A:AD:65:C3:3E:A2:4C:30:72:73:02:C5:F3:D4:0E:B7:FC:2F", - "SHA512":"CA:A0:8C:B9:FE:9D:C2:72:18:57:08:E9:4B:11:B7:BC:4E:F7:52:C8:9C:76:03:45:B4:B6:C5:D2:DC:E8:79:43:D7:71:1F:5C:97:FA:B2:F3:ED:AE:19:BD:A9:3B:DB:9F:A5:B4:8D:57:3F:40:34:29:50:AA:AA:0A:93:D8:D7:54" - }, - "dns_alt_names":["DNS:puppet","DNS:mycertname"] - } - - -#### Revoking a certificate - - PUT /puppet-ca/v1/certificate_status/mycertname?environment=production HTTP/1.1 - Content-Type: text/pson - Content-Length: 27 - - {"desired_state":"revoked"} - -This has no meaningful return value. - - -#### Deleting the certificate information - - DELETE /puppet-ca/v1/certificate_status/mycertname?environment=production HTTP/1.1 - -Gets the response: - - "Deleted for mycertname: Puppet::SSL::Certificate, Puppet::SSL::Key" - -Schema ------ - -Find and search operations return objects which -conform to [the host schema.](../schemas/host.json) diff --git a/docs/_openvox_8x/http_api/http_environment.md b/docs/_openvox_8x/http_api/http_environment.md deleted file mode 100644 index b9a6c1e73..000000000 --- a/docs/_openvox_8x/http_api/http_environment.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Environment' -canonical: "/puppet/latest/http_api/http_environment.html" ---- - -Environment Catalog -=================== - -**Warning: the format of the response for this endpoint will change in a -future version in an incompatible way. It should be considered private for -the time being** - -Issuing a `GET` request against this endpoint causes the compiler to -compile an _environment catalog_ and return it. - -Get ---- - -Get the catalog for an environment - - GET /puppet/v3/environment/:environment - -### Supported Response Formats - -`application/json` - -### Parameters - -None - -### Example Request & Response - - GET /puppet/v3/environment/production - - HTTP 200 OK - Content-Type: application/json - - { - "environment": "production", - "applications": { - "Webapp[pao]": { - "Db[pao_db]": { - "produces": [ "Sql[pao_db]" ], - "consumes": [], - "node": "agent1" }, - "Web[pao_w1]": { - "produces": [ "Http[pao_w1]" ], - "consumes": [ "Sql[pao_db]" ], - "node": "agent2" }, - "Web[pao_w2]": { - "produces": [ "Http[pao_w2]" ], - "consumes": [ "Sql[pao_db]" ], - "node": "agent2" }, - "Web[pao_w3]": { - "produces": [ "Http[pao_w3]" ], - "consumes": [ "Sql[pao_db]" ], - "node": "agent2" }, - "Lb[pao_lb]": { - "produces": [], - "consumes": [ "Http[pao_w1]", "Http[pao_w2]", "Http[pao_w3]" ], - "node": "agent3" } - } - } - } - -The response contains the name of the environment in the `environment` key, -and a list of applications in that environment in the `applications` -hash. The type/title of each application is used as the key in that hash, -and the entry for that application consists of a hash of the components, -again keyed by the type and title of the component. - -For each component, the catalog indicates what service resources the -component `produces` and `consumes`, as well as the `node` to which that -component is mapped. - -#### Planned response change - -The response format is likely to change in the following way: - -* the `applications` hash will become an array of hashes, where each hash - represents an application with separate keys for type and title, and for - the components of the application -* the components of an application will similarly be represented as an - array of hashes, similar to the format used today, but with the addition - of the component's type and title inside the hash diff --git a/docs/_openvox_8x/http_api/http_file_content.md b/docs/_openvox_8x/http_api/http_file_content.md deleted file mode 100644 index 4cc30f057..000000000 --- a/docs/_openvox_8x/http_api/http_file_content.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: File Content' -canonical: "/puppet/latest/http_api/http_file_content.html" ---- - -File Content -============= - -The `file_content` endpoint returns the contents of the specified file. - -Find ----- - -Get a file. - - GET /puppet/v3/file_content/:mount_point/:name - -The endpoint path includes a `:mount_point` which can be one of the following types: - -* Custom file serving mounts as specified in fileserver.conf --- see [the docs on configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). -* `modules/` --- a semi-magical mount point which allows access to the `files` subdirectory of `` --- see [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html). -* `plugins` --- a highly magical mount point which merges the `lib` directory of every module together. Used for syncing plugins; not intended for general consumption. Per-module sub-paths can not be specified. -* `pluginfacts` --- a highly magical mount point which merges the `facts.d` directory of every module together. Used for syncing external facts; not intended for general consumption. Per-module sub-paths can not be specified. -* `tasks/` --- a semi-magical mount point which allows access to files in the `tasks` subdirectory of `` --- see the [the docs on file serving](https://puppet.com/docs/puppet/latest/file_serving.html). - -`:name` is the path to the file within the `:mount_point` that is requested. - -### Supported HTTP Methods - -GET - -### Supported Response Formats - -`application/octet-stream` - -### Parameters - -None - -### Notes - -### Responses - -#### File found - - GET /puppet/v3/file_content/modules/example/my_file?environment=env - Accept: application/octet-stream - - HTTP/1.1 200 OK - Content-Type: application/octet-stream - Content-Length: 16 - - this is my file - - -#### File not found - - GET /puppet/v3/file_content/modules/example/not_found?environment=env - Accept: application/octet-stream - - HTTP/1.1 404 Not Found - Content-Type: text/plain - - Not Found: Could not find file_content modules/example/not_found - -#### No file name given - - GET /puppet/v3/file_content?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /puppet/v3/file_content/ - -Schema ------- - -A `file_content` response body is not structured data according to any standard scheme such as -json/pson/yaml, so no schema is applicable. diff --git a/docs/_openvox_8x/http_api/http_resource_type.md b/docs/_openvox_8x/http_api/http_resource_type.md deleted file mode 100644 index 92786b440..000000000 --- a/docs/_openvox_8x/http_api/http_resource_type.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -layout: default -built_from_commit: 0b327984fb25fa7cffbd3a304913ca987f4df3d9 -title: 'Puppet HTTP API: Resource Type' -canonical: "/puppet/latest/http_api/http_resource_type.html" ---- - -Resource Type -============= - -> **Deprecation note:** This endpoint was -[deprecated](https://docs.puppet.com/puppet/4.5/reference/deprecated_api.html) in Puppet -4.5.0 in favor of the -[`environment_classes`](https://docs.puppet.com/puppetserver/2.5/puppet-api/v3/environment_classes.html) -endpoint provided by Puppet Server 2.3.0 and later. - -The `resource_type` and `resource_types` endpoints return information about the -following kinds of objects available to the OpenVox Server: - -* Classes (`class myclass { ... }`) -* Defined types (`define mytype ($parameter) { ... }`) -* Node definitions (`node 'web01.example.com' { ... }`) - -For an object to be available to the OpenVox Server, it must be present in the -site manifest (configured by the `manifest` setting) or in a module located in -the modulepath (configured by the `modulepath` setting; classes and defined -types only). - -Note that this endpoint does **not** return information about native resource -types written in Ruby. - -See the end of this page for the source manifest used to generate all example -responses. - -Find ----- - -Get info about a specific class, defined type, or node, by name. Returns a -single resource_type response object (see "Schema" below). - - GET /puppet/v3/resource_type/:class_type_or_node_name?environment=:environment - -> **Note:** Although no two classes or defined types may have the same name, -> it's possible for a node definition to have the same name as a class or -> defined type. If this happens, the class or defined type will be returned -> instead of the node definition. The order in which kinds of objects are -> searched is classes, then defined types, then node definitions. - - -### Supported HTTP Methods - -GET - -### Supported Formats - -PSON - -### Parameters - -None - -### Responses - -#### Resource Type Found - - GET /puppet/v3/resource_type/athing?environment=env - - HTTP 200 OK - Content-Type: text/pson - - { - "line": 7, - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "name":"athing", - "kind":"class" - } - -#### Resource Type Not Found - - GET /puppet/v3/resource_type/resource_type_does_not_exist?environment=env - - HTTP 404 Not Found - Content-Type: text/plain - - Not Found: Could not find resource_type resource_type_does_not_exist - -#### No Resource Type Name Given - - GET /puppet/v3/resource_type?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /env/resource_type/ - -Search ------- - -List all resource types matching a regular expression. Returns an array of -resource_type response objects (see "Schema" below). - - GET /puppet/v3/resource_types/:search_string?environment=:environment - -The `search_string` is required. It must be either a Ruby regular expression or -the string `*` (which will match all resource types). Surrounding slashes are -stripped. Note that if you want to use the `?` character in a regular -expression, it must be escaped as `%3F`. - -### Supported HTTP Methods - -GET - -### Supported Formats - -Accept: pson, text/pson - -### Parameters - -* `kind`: Optional. Filter the returned resource types by the `kind` field. - Valid values are `class`, `node`, and `defined_type`. - -### Responses - -#### Search With Results - - GET /puppet/v3/resource_types/*?environment=env - - HTTP 200 OK - Content-Type: text/pson - - [ - { - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "kind": "class", - "line": 7, - "name": "athing" - }, - { - "doc": "An example class\n", - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "kind": "class", - "line": 11, - "name": "bthing", - "parent": "athing" - }, - { - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "kind": "defined_type", - "line": 1, - "name": "hello", - "parameters": { - "a": "{key2 => \"val2\", key => \"val\"}", - "message": "$title" - } - }, - { - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "kind": "node", - "line": 14, - "name": "web01.example.com" - }, - { - "file": "/etc/puppetlabs/puppet/manifests/site.pp", - "kind": "node", - "line": 17, - "name": "default" - } - ] - - -#### Search Not Found - - GET /puppet/v3/resource_types/pattern.that.finds.no.resources?environment=env - - HTTP/1.1 404 Not Found: Could not find instances in resource_type with 'pattern.that.finds.no.resources' - Content-Type: text/plain - - Not Found: Could not find instances in resource_type with 'pattern.that.finds.no.resources' - -#### No Search Term Given - - GET /puppet/v3/resource_types?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - No request key specified in /puppet/v3/resource_types - -#### Search Term Is an Invalid Regular Expression - -Searching on `[-` for instance. - - GET /puppet/v3/resource_types/%5b-?environment=env - - HTTP/1.1 400 Bad Request - Content-Type: text/plain - - Invalid regex '[-': premature end of char-class: /[-/ - -### Examples - -List all classes: - - GET /puppet/v3/resource_types/*?environment=:environment&kind=class - -List matching a regular expression: - - GET /puppet/v3/resource_types/foo.*bar?environment=:environment - -Schema ------- - -A `resource_type` response body conforms to -[the `resource_type` schema.](../schemas/resource_type.json) - -Source ------- - -Example site.pp used to generate all the responses in this file: - - define hello ($message = $title, $a = { key => 'val', key2 => 'val2' }) { - notify {$message: } - } - - hello { "there": } - - class athing { - } - - # An example class - class bthing inherits athing { - } - - node 'web01.example.com' {} - node default {} - diff --git a/docs/_openvox_8x/http_api/http_status.md b/docs/_openvox_8x/http_api/http_status.md deleted file mode 100644 index aeaace301..000000000 --- a/docs/_openvox_8x/http_api/http_status.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: Status' -canonical: "/puppet/latest/http_api/http_status.html" ---- - -Status -============= - -The `status` endpoint provides information about a running master. - -Find ----- - -Get status for a master - - GET /puppet/v3/status/:name?environment=:environment - -The `environment` parameter and the `:name` are both required, but have no -effect on the response. The `environment` must be a valid environment. - -### Supported HTTP Methods - -GET - -### Supported Response Formats - -`application/json`, `text/pson` - -### Parameters - -None - -### Example Response - - GET /puppet/v3/status/whatever?environment=env - - HTTP 200 OK - Content-Type: application/json - - {"is_alive":true,"version":"3.3.2"} - -Schema ------- - -A status response body conforms to [the status schema.](../schemas/status.json) diff --git a/docs/_openvox_8x/http_api/pson.md b/docs/_openvox_8x/http_api/pson.md deleted file mode 100644 index df56421ce..000000000 --- a/docs/_openvox_8x/http_api/pson.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -layout: default -built_from_commit: 8c9dd1ff315b738818307cc895942164aba30730 -title: 'Puppet HTTP API: PSON' -canonical: "/puppet/latest/http_api/pson.html" ---- - -PSON -============= - -PSON is a variant of [JSON](http://json.org) that puppet uses for serializing -data to transmit across the network or store on disk. Whereas JSON requires -that the serialized form is valid unicode (usually UTF-8), PSON is 8-bit ASCII, -which allows it to represent arbitrary byte sequences in strings. - -Puppet uses the MIME types "pson" and "text/pson" to refer to PSON. - -Differences from JSON ---------------------- - -PSON does *not differ* from JSON in its representation of objects, arrays, -numbers, booleans, and null values. PSON *does* serialize strings differently -from JSON. - -A PSON string is a sequence of 8-bit ASCII encoded data. It must start and end -with " (ASCII 0x22) characters. Between these characters it may contain any -byte sequence. Some individual characters are represented by a sequence of -characters: - - | Byte | ASCII Character | Encoded Sequence | Encoded ASCII Sequence | - | ---- | --------------- | ---------------- | ---------------------- | - | 0x22 | " | 0x5C, 0x22 | \" | - | 0x5c | \ | 0x5C, 0x5C | \\ | - | 0x08 | Backspace | 0x5C, 0x62 | \b | - | 0x09 | Horizontal Tab | 0x5C, 0x74 | \t | - | 0x0A | Line Feed | 0x5C, 0x6E | \n | - | 0x0C | Form Feed | 0x5C, 0x66 | \f | - | 0x0D | Carriage Return | 0x5C, 0x72 | \r | - -In addition, any character between 0x00 and 0x1F, (except the ones listed -above) must be encoded as a six byte sequence of \u followed by four ASCII -digits of the hex number of the desired character. For example the ASCII -Record Separator character (0x1E) is represented as \u001E (0x5C, 0x75, 0x30, -0x30, 0x31, 0x45). - -Decoding PSON Using JSON Parsers --------------------------------- - -Many languages have JSON parsers already, which can often be used to parse PSON -data. Although JSON requires that it is encoded as unicode most parsers will -produce usable output from PSON if they are instructed to interpret the input -as Latin-1 encoding. - -In all these examples there is a file available called `data.pson` that -contains the ruby structure `{ "data" => "\x07\x08\xC3\xC3" }` encoded as -PSON (the value is an invalid unicode sequence). In bytes the data is: - - 0x7b 0x22 0x64 0x61 0x74 0x61 0x22 0x3a 0x22 0x5c 0x75 0x30 0x30 0x30 0x37 0x5c 0x62 0xc3 0xc3 0x22 0x7d - -Python Example: - - >>> import json - >>> json.load(open("data.pson"), "latin_1") - {u'data': u'\x07\x08\xc3\xc3'} - -Clojure Example: - - user> (parse-string (slurp "data.pson" :encoding "ISO-8859-1")) - {"data" "^G\bÃÃ"} From 6cf91723ece629baa1f82b781d0e664f5fcc07c0 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Tue, 26 May 2026 15:25:40 -0400 Subject: [PATCH 2/3] fix: handle absolute nav links without prepending collection base URL Nav links starting with '/' are already absolute site paths. The old code unconditionally prepended nav_base (also starting with '/'), producing a double-prefix like /openvox/latest//openvox-server/latest/... and causing a 404. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Michael Harp --- _includes/nav-item.html | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/_includes/nav-item.html b/_includes/nav-item.html index 06f4aa984..8d5cd1347 100644 --- a/_includes/nav-item.html +++ b/_includes/nav-item.html @@ -28,7 +28,16 @@

{{ include.item.text }}

{% elsif include.item.link %} - {% assign nav_item_url = include.item.link | prepend: nav_base %} + {%- comment -%} + Links starting with '/' are already absolute site paths. Prepending nav_base (which also + starts with '/') would produce a broken double-prefix like /openvox/latest//other/page.html. + {%- endcomment -%} + {% assign nav_link_first_char = include.item.link | slice: 0 %} + {% if nav_link_first_char == '/' %} + {% assign nav_item_url = include.item.link %} + {% else %} + {% assign nav_item_url = include.item.link | prepend: nav_base %} + {% endif %}
From 585bec9ce28379aa101ac89018757b997e749969 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Thu, 28 May 2026 12:22:37 -0400 Subject: [PATCH 3/3] fix: replace old puppet.com links with openvox-docs equivalents In http_file_metadata.md and http_file_content.md, replace three puppet.com links in the mount point lists with internal openvox-docs pages: config_file_fileserver.html for mount point configuration and file_serving.html for file serving docs. Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Michael Harp --- docs/_openvox-server_8x/http_file_content.md | 12 ++++++------ docs/_openvox-server_8x/http_file_metadata.md | 12 ++++++------ 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/_openvox-server_8x/http_file_content.md b/docs/_openvox-server_8x/http_file_content.md index 2ade5862f..88b47f75a 100644 --- a/docs/_openvox-server_8x/http_file_content.md +++ b/docs/_openvox-server_8x/http_file_content.md @@ -15,16 +15,16 @@ Get a file. The endpoint path includes a `:mount_point` which can be one of the following types: -- Custom file serving mounts as specified in `fileserver.conf` — see the Puppet docs on - [configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). -- `modules/` — allows access to the `files` subdirectory of `` — see the Puppet docs on - [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- Custom file serving mounts as specified in `fileserver.conf` — see + [configuring mount points](/openvox/8.x/config_file_fileserver.html). +- `modules/` — allows access to the `files` subdirectory of `` — see + [file serving](/openvox/8.x/file_serving.html). - `plugins` — merges the `lib` directory of every module together. Used for syncing plugins; not intended for general consumption. Per-module sub-paths cannot be specified. - `pluginfacts` — merges the `facts.d` directory of every module together. Used for syncing external facts; not intended for general consumption. Per-module sub-paths cannot be specified. -- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see the Puppet docs on - [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see + [file serving](/openvox/8.x/file_serving.html). `:name` is the path to the file within the `:mount_point` that is requested. diff --git a/docs/_openvox-server_8x/http_file_metadata.md b/docs/_openvox-server_8x/http_file_metadata.md index 8e4573430..c14c047aa 100644 --- a/docs/_openvox-server_8x/http_file_metadata.md +++ b/docs/_openvox-server_8x/http_file_metadata.md @@ -17,16 +17,16 @@ of the following three types: The endpoint path includes a `:mount` which can be one of the following types: -- Custom file serving mounts as specified in `fileserver.conf` — see the Puppet docs on - [configuring mount points](https://puppet.com/docs/puppet/latest/file_serving.html). -- `modules/` — allows access to the `files` subdirectory of `` — see the Puppet docs on - [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- Custom file serving mounts as specified in `fileserver.conf` — see + [configuring mount points](/openvox/8.x/config_file_fileserver.html). +- `modules/` — allows access to the `files` subdirectory of `` — see + [file serving](/openvox/8.x/file_serving.html). - `plugins` — merges the `lib` directory of every module together. Used for syncing plugins; not intended for general consumption. Per-module sub-paths cannot be specified. - `pluginfacts` — merges the `facts.d` directory of every module together. Used for syncing external facts; not intended for general consumption. Per-module sub-paths cannot be specified. -- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see the Puppet docs on - [file serving](https://puppet.com/docs/puppet/latest/file_serving.html). +- `tasks/` — allows access to files in the `tasks` subdirectory of `` — see + [file serving](/openvox/8.x/file_serving.html). ## Find