diff --git a/configs/Makefile.am b/configs/Makefile.am index 409dbc0c161..95499b5e2f4 100644 --- a/configs/Makefile.am +++ b/configs/Makefile.am @@ -39,7 +39,8 @@ dist_sysconf_DATA = \ splitdns.config.default \ ssl_multicert.config.default \ strategies.yaml.default \ - volume.config.default + volume.config.default \ + jsonrpc.yaml.default install-exec-hook: for dfltcfgfile in $(dist_sysconf_DATA) $(nodist_sysconf_DATA) ; \ diff --git a/configs/jsonrpc.yaml.default b/configs/jsonrpc.yaml.default new file mode 100644 index 00000000000..82665a22544 --- /dev/null +++ b/configs/jsonrpc.yaml.default @@ -0,0 +1,14 @@ +# jsonrpc.yaml +# +# Documentation: +# https://docs.trafficserver.apache.org/en/latest/admin-guide/files/jsonrpc.yaml.en.html +# +# This configuration file can be used to configure some specific values of +# the jsonrpc endpoint. +# +# Example: + +# rpc: +# enabled: true +# unix: +# restricted_api: true diff --git a/doc/admin-guide/files/index.en.rst b/doc/admin-guide/files/index.en.rst index 9925ec2eef0..4bf2aca3aaf 100644 --- a/doc/admin-guide/files/index.en.rst +++ b/doc/admin-guide/files/index.en.rst @@ -39,6 +39,7 @@ Configuration Files storage.config.en strategies.yaml.en volume.config.en + jsonrpc.yaml.en :doc:`cache.config.en` Defines if, how, and for what durations |TS| caches objects, based on @@ -87,6 +88,9 @@ Configuration Files :doc:`volume.config.en` Defines cache space usage by individual protocols. +:doc:`jsonrpc.yaml.en` + Defines some of the configurable arguments of the jsonrpc endpoint. + .. note:: Currently the YAML parsing library has a bug where line number counting diff --git a/doc/admin-guide/jsonrpc/index.en.rst b/doc/admin-guide/files/jsonrpc.yaml.en.rst similarity index 63% rename from doc/admin-guide/jsonrpc/index.en.rst rename to doc/admin-guide/files/jsonrpc.yaml.en.rst index 84f0d1d5c34..4c9970988d1 100644 --- a/doc/admin-guide/jsonrpc/index.en.rst +++ b/doc/admin-guide/files/jsonrpc.yaml.en.rst @@ -21,29 +21,39 @@ .. default-domain:: cpp .. |RPC| replace:: JSONRPC 2.0 +.. configfile:: jsonrpc.yaml .. _admin-jsonrpc: -JSONRPC -******* + +jsonrpc.yaml +************ .. _admin-jsonrpc-description: +The :file:`jsonrpc.yaml` file defines some of the configurable arguments of the +jsonrpc endpoint. + Description =========== -|TS| Implements and exposes management calls using a JSONRPC API. This API is base on the following two things: - -* `JSON `_ format. Lightweight data-interchange format. It is easy for humans to read and write. - It is easy for machines to parse and generate. It's basically a collection of name/value pairs. - -* `JSONRPC 2.0 `_ protocol. Stateless, light-weight remote procedure call (RPC) protocol. - Primarily this specification defines several data structures and the rules around their processing. +|TS| Implements and exposes management calls using a JSONRPC API. This API is +base on the following two things: +* `JSON `_ format. Lightweight + data-interchange format. It is easy for humans to read and write. + It is easy for machines to parse and generate. It's basically a collection of + name/value pairs. -In order for programs to communicate with |TS|, the server exposes a ``JSONRRPC 2.0`` API where programs can communicate with it. +* `JSONRPC 2.0 `_ protocol. Stateless, + light-weight remote procedure call (RPC) protocol. + Primarily this specification defines several data structures and the rules + around their processing. +In order for programs to communicate with |TS|, the server exposes a +``JSONRRPC 2.0`` API where programs can communicate with it. In this document you +will find some of the configurable arguments that can be changed. .. _admnin-jsonrpc-configuration: @@ -51,50 +61,52 @@ In order for programs to communicate with |TS|, the server exposes a ``JSONRRPC Configuration ============= -The |RPC| server can be configured using the following configuration file. - - .. note:: |TS| will start the |RPC| server without any need for configuration. +If a non-default configuration is needed, the following describes the configuration +structure. -If a non-default configuration is needed, the following describes the structure. - - -File `jsonrpc.yaml` is a YAML format. The default configuration is:: +File `jsonrpc.yaml` is a YAML format. The default configuration is: +.. code:: yaml - #YAML rpc: - enabled: true - unix: - lock_path_name: /tmp/conf_jsonrpc.lock - sock_path_name: /tmp/conf_jsonrpc.sock - backlog: 5 - max_retry_on_transient_errors: 64 - restricted_api: true + enabled: true + unix: + restricted_api: true -===================== ========================================================================================= +===================== ========================================================== Field Name Description -===================== ========================================================================================= -``enabled`` Enable/disable toggle for the whole implementation, server will not start if this is false/no +===================== ========================================================== +``enabled`` Enable/disable toggle for the whole implementation, server + will not start if this is false/no ``unix`` Specific definitions as per transport. -===================== ========================================================================================= +===================== ========================================================== -IPC Socket (``unix``): +IPC Socket (``unix``) +--------------------- -===================================== ========================================================================================= +===================================== ========================================== Field Name Description -===================================== ========================================================================================= -``lock_path_name`` Lock path, including the file name. (changing this may have impacts in :program:`traffic_ctl`) -``sock_path_name`` Sock path, including the file name. This will be used as ``sockaddr_un.sun_path``. (changing this may have impacts in :program:`traffic_ctl`) +===================================== ========================================== +``lock_path_name`` Lock path, including the file name. + (changing this may have impacts in + :program:`traffic_ctl`) +``sock_path_name`` Sock path, including the file name. This + will be used as ``sockaddr_un.sun_path`` + (changing this may have impacts in :program:`traffic_ctl`) ``backlog`` Check https://man7.org/linux/man-pages/man2/listen.2.html -``max_retry_on_transient_errors`` Number of times the implementation is allowed to retry when a transient error is encountered. -``restricted_api`` Used to set rpc unix socket permissions. If restricted `0700` will be set, otherwise `0777`. ``true`` by default. -===================================== ========================================================================================= +``max_retry_on_transient_errors`` Number of times the implementation is + allowed to retry when a transient error is + encountered. +``restricted_api`` Used to set rpc unix socket permissions. + If restricted `0700` will be set, otherwise + `0777`. ``true`` by default. +===================================== ========================================== .. note:: diff --git a/doc/admin-guide/index.en.rst b/doc/admin-guide/index.en.rst index 664ff41a84f..0557b691c4a 100644 --- a/doc/admin-guide/index.en.rst +++ b/doc/admin-guide/index.en.rst @@ -40,7 +40,6 @@ Table of Contents: layer-4-routing.en performance/index.en files/index.en - jsonrpc/index.en Audience ========