diff --git a/antsibull/schemas/base.py b/antsibull/schemas/base.py index b4d738f8..f78c5721 100644 --- a/antsibull/schemas/base.py +++ b/antsibull/schemas/base.py @@ -129,6 +129,11 @@ def handle_renamed_attribute(cls, values): _SENTINEL = object() +#: Constrained string for valid Ansible cli args. +#: Must not start or end with an underscore, must not contain double underscores, lowercase ascii +#: letters, digits, and single underscores are okay. +REQUIRED_CLI_F = p.Field(..., regex='^[a-z0-9]+(_[a-z0-9]+)*$') + #: Constrained string for valid Ansible environment variables REQUIRED_ENV_VAR_F = p.Field(..., regex='[A-Z_]+') diff --git a/antsibull/schemas/plugin.py b/antsibull/schemas/plugin.py index d9815707..ee40079e 100644 --- a/antsibull/schemas/plugin.py +++ b/antsibull/schemas/plugin.py @@ -12,7 +12,7 @@ import pydantic as p -from .base import (REQUIRED_ENV_VAR_F, RETURN_TYPE_F, +from .base import (REQUIRED_CLI_F, REQUIRED_ENV_VAR_F, RETURN_TYPE_F, COLLECTION_NAME_F, BaseModel, DeprecationSchema, DocSchema, LocalConfig, OptionsSchema, list_from_scalars, is_json_value, normalize_return_type_names, transform_return_docs) @@ -20,6 +20,13 @@ _SENTINEL = object() +class OptionCliSchema(BaseModel): + name: str = REQUIRED_CLI_F + deprecated: DeprecationSchema = p.Field({}) + version_added: str = 'historical' + version_added_collection: str = COLLECTION_NAME_F + + class OptionEnvSchema(BaseModel): name: str = REQUIRED_ENV_VAR_F deprecated: DeprecationSchema = p.Field({}) @@ -114,6 +121,7 @@ class OuterReturnSchema(ReturnSchema): class PluginOptionsSchema(OptionsSchema): + cli: t.List[OptionCliSchema] = [] env: t.List[OptionEnvSchema] = [] ini: t.List[OptionIniSchema] = [] suboptions: t.Dict[str, 'PluginOptionsSchema'] = {} diff --git a/tests/functional/schema/good_data/one_become_results.json b/tests/functional/schema/good_data/one_become_results.json index 8f57ae76..5ba58a0e 100644 --- a/tests/functional/schema/good_data/one_become_results.json +++ b/tests/functional/schema/good_data/one_become_results.json @@ -22,6 +22,7 @@ "become_pass": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_cache_results.json b/tests/functional/schema/good_data/one_cache_results.json index 80dc04f1..d8e81259 100644 --- a/tests/functional/schema/good_data/one_cache_results.json +++ b/tests/functional/schema/good_data/one_cache_results.json @@ -19,6 +19,7 @@ "_prefix": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -52,6 +53,7 @@ "_timeout": { "aliases": [], "choices": [], + "cli": [], "default": 86400, "deprecated": {}, "description": [ @@ -85,6 +87,7 @@ "_uri": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_cliconf_results.json b/tests/functional/schema/good_data/one_cliconf_results.json index a3a5456a..311e09fc 100644 --- a/tests/functional/schema/good_data/one_cliconf_results.json +++ b/tests/functional/schema/good_data/one_cliconf_results.json @@ -19,6 +19,7 @@ "eos_use_sessions": { "aliases": [], "choices": [], + "cli": [], "default": 1, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_connection_results.json b/tests/functional/schema/good_data/one_connection_results.json index ab866d56..589961df 100644 --- a/tests/functional/schema/good_data/one_connection_results.json +++ b/tests/functional/schema/good_data/one_connection_results.json @@ -19,6 +19,7 @@ "become": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -60,6 +61,7 @@ "become_method": { "aliases": [], "choices": [], + "cli": [], "default": "sudo", "deprecated": {}, "description": [ @@ -100,6 +102,7 @@ "host": { "aliases": [], "choices": [], + "cli": [], "default": "inventory_hostname", "deprecated": {}, "description": [ @@ -125,6 +128,7 @@ "network_os": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -150,6 +154,7 @@ "password": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -187,6 +192,7 @@ "persistent_command_timeout": { "aliases": [], "choices": [], + "cli": [], "default": 30, "deprecated": {}, "description": [ @@ -227,6 +233,7 @@ "persistent_connect_timeout": { "aliases": [], "choices": [], + "cli": [], "default": 30, "deprecated": {}, "description": [ @@ -267,6 +274,7 @@ "persistent_log_messages": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -308,6 +316,7 @@ "port": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -349,6 +358,7 @@ "remote_user": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -390,6 +400,7 @@ "use_proxy": { "aliases": [], "choices": [], + "cli": [], "default": 1, "deprecated": {}, "description": [ @@ -415,6 +426,7 @@ "use_ssl": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -440,6 +452,7 @@ "validate_certs": { "aliases": [], "choices": [], + "cli": [], "default": 1, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_httpapi_results.json b/tests/functional/schema/good_data/one_httpapi_results.json index 426469c4..7a831a22 100644 --- a/tests/functional/schema/good_data/one_httpapi_results.json +++ b/tests/functional/schema/good_data/one_httpapi_results.json @@ -19,6 +19,7 @@ "root_path": { "aliases": [], "choices": [], + "cli": [], "default": "/restconf", "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_inventory_results.json b/tests/functional/schema/good_data/one_inventory_results.json index be682553..f2486cec 100644 --- a/tests/functional/schema/good_data/one_inventory_results.json +++ b/tests/functional/schema/good_data/one_inventory_results.json @@ -24,6 +24,7 @@ "aws_access_key_id" ], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -63,6 +64,7 @@ "boto_profile" ], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -96,6 +98,7 @@ "aws_secret_access_key" ], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -133,6 +136,7 @@ "aws_security_token": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -170,6 +174,7 @@ "cache": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -203,6 +208,7 @@ "cache_connection": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -249,6 +255,7 @@ "cache_plugin": { "aliases": [], "choices": [], + "cli": [], "default": "memory", "deprecated": {}, "description": [ @@ -295,6 +302,7 @@ "cache_prefix": { "aliases": [], "choices": [], + "cli": [], "default": "ansible_inventory_", "deprecated": {}, "description": [ @@ -341,6 +349,7 @@ "cache_timeout": { "aliases": [], "choices": [], + "cli": [], "default": 3600, "deprecated": {}, "description": [ @@ -387,6 +396,7 @@ "compose": { "aliases": [], "choices": [], + "cli": [], "default": {}, "deprecated": {}, "description": [ @@ -405,6 +415,7 @@ "filters": { "aliases": [], "choices": [], + "cli": [], "default": {}, "deprecated": {}, "description": [ @@ -424,6 +435,7 @@ "groups": { "aliases": [], "choices": [], + "cli": [], "default": {}, "deprecated": {}, "description": [ @@ -442,6 +454,7 @@ "hostnames": { "aliases": [], "choices": [], + "cli": [], "default": [], "deprecated": {}, "description": [ @@ -462,6 +475,7 @@ "iam_role_arn": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -480,6 +494,7 @@ "include_extra_api_calls": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -499,6 +514,7 @@ "keyed_groups": { "aliases": [], "choices": [], + "cli": [], "default": [], "deprecated": {}, "description": [ @@ -519,6 +535,7 @@ "choices": [ "aws_ec2" ], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -537,6 +554,7 @@ "regions": { "aliases": [], "choices": [], + "cli": [], "default": [], "deprecated": {}, "description": [ @@ -556,6 +574,7 @@ "strict": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -575,6 +594,7 @@ "strict_permissions": { "aliases": [], "choices": [], + "cli": [], "default": 1, "deprecated": {}, "description": [ @@ -594,6 +614,7 @@ "use_contrib_script_compatible_sanitization": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_lookup_results.json b/tests/functional/schema/good_data/one_lookup_results.json index 95666cbc..f2dda362 100644 --- a/tests/functional/schema/good_data/one_lookup_results.json +++ b/tests/functional/schema/good_data/one_lookup_results.json @@ -18,6 +18,7 @@ "_raw": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -36,6 +37,7 @@ "client_cert": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -69,6 +71,7 @@ "datacenter": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -87,6 +90,7 @@ "host": { "aliases": [], "choices": [], + "cli": [], "default": "localhost", "deprecated": {}, "description": [ @@ -121,6 +125,7 @@ "index": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -139,6 +144,7 @@ "port": { "aliases": [], "choices": [], + "cli": [], "default": 8500, "deprecated": {}, "description": [ @@ -158,6 +164,7 @@ "recurse": { "aliases": [], "choices": [], + "cli": [], "default": 0, "deprecated": {}, "description": [ @@ -176,6 +183,7 @@ "scheme": { "aliases": [], "choices": [], + "cli": [], "default": "http", "deprecated": {}, "description": [ @@ -195,6 +203,7 @@ "token": { "aliases": [], "choices": [], + "cli": [], "default": null, "deprecated": {}, "description": [ @@ -213,6 +222,7 @@ "validate_certs": { "aliases": [], "choices": [], + "cli": [], "default": 1, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_netconf_results.json b/tests/functional/schema/good_data/one_netconf_results.json index 62dfc574..eb1e233c 100644 --- a/tests/functional/schema/good_data/one_netconf_results.json +++ b/tests/functional/schema/good_data/one_netconf_results.json @@ -19,6 +19,7 @@ "ncclient_device_handler": { "aliases": [], "choices": [], + "cli": [], "default": "iosxr", "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/one_shell_results.json b/tests/functional/schema/good_data/one_shell_results.json index da43d782..412b0d9f 100644 --- a/tests/functional/schema/good_data/one_shell_results.json +++ b/tests/functional/schema/good_data/one_shell_results.json @@ -17,6 +17,7 @@ "admin_users": { "aliases": [], "choices": [], + "cli": [], "default": [ "root", "toor" @@ -60,6 +61,7 @@ "async_dir": { "aliases": [], "choices": [], + "cli": [], "default": "~/.ansible_async", "deprecated": {}, "description": [ @@ -100,6 +102,7 @@ "environment": { "aliases": [], "choices": [], + "cli": [], "default": {}, "deprecated": {}, "description": [ @@ -118,6 +121,7 @@ "remote_tmp": { "aliases": [], "choices": [], + "cli": [], "default": "~/.ansible/tmp", "deprecated": {}, "description": [ @@ -164,6 +168,7 @@ "system_tmpdirs": { "aliases": [], "choices": [], + "cli": [], "default": [ "/var/tmp", "/tmp" diff --git a/tests/functional/schema/good_data/one_vars_results.json b/tests/functional/schema/good_data/one_vars_results.json index fd563dff..7805678d 100644 --- a/tests/functional/schema/good_data/one_vars_results.json +++ b/tests/functional/schema/good_data/one_vars_results.json @@ -21,6 +21,7 @@ "_valid_extensions": { "aliases": [], "choices": [], + "cli": [], "default": [ ".yml", ".yaml", @@ -63,6 +64,7 @@ "task", "inventory" ], + "cli": [], "default": null, "deprecated": {}, "description": [ diff --git a/tests/functional/schema/good_data/ssh_connection.json b/tests/functional/schema/good_data/ssh_connection.json new file mode 100644 index 00000000..b45ca440 --- /dev/null +++ b/tests/functional/schema/good_data/ssh_connection.json @@ -0,0 +1,673 @@ +{ + "ansible.builtin.ssh": { + "doc": { + "author": "ansible (@core)", + "collection": "ansible.builtin", + "description": [ + "This connection plugin allows ansible to communicate to the target machines via normal ssh command line.", + "Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using this connection plugin (which is the default). The use of ``ssh-agent`` is highly recommended." + ], + "filename": "/srv/ansible/vanilla/lib/ansible/plugins/connection/ssh.py", + "name": "ssh", + "notes": [ + "Many options default to 'None' here but that only means we don't override the ssh tool's defaults and/or configuration. For example, if you specify the port in this plugin it will override any C(Port) entry in your C(.ssh/config)." + ], + "options": { + "control_path": { + "description": [ + "This is the location to save ssh's ControlPath sockets, it uses ssh's variable substitution.", + "Since 2.3, if null (default), ansible will generate a unique hash. Use `%(directory)s` to indicate where to use the control dir path setting.", + "Before 2.3 it defaulted to `control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r`.", + "Be aware that this setting is ignored if `-o ControlPath` is set in ssh args." + ], + "env": [ + { + "name": "ANSIBLE_SSH_CONTROL_PATH" + } + ], + "ini": [ + { + "key": "control_path", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_control_path", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "control_path_dir": { + "default": "~/.ansible/cp", + "description": [ + "This sets the directory to use for ssh control path if the control path setting is null.", + "Also, provides the `%(directory)s` variable for the control path setting." + ], + "env": [ + { + "name": "ANSIBLE_SSH_CONTROL_PATH_DIR" + } + ], + "ini": [ + { + "key": "control_path_dir", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_control_path_dir", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "host": { + "description": "Hostname/ip to connect to.", + "vars": [ + { + "name": "inventory_hostname" + }, + { + "name": "ansible_host" + }, + { + "name": "ansible_ssh_host" + }, + { + "name": "delegated_vars['ansible_host']" + }, + { + "name": "delegated_vars['ansible_ssh_host']" + } + ] + }, + "host_key_checking": { + "description": "Determines if ssh should check host keys", + "env": [ + { + "name": "ANSIBLE_HOST_KEY_CHECKING" + }, + { + "name": "ANSIBLE_SSH_HOST_KEY_CHECKING", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "host_key_checking", + "section": "defaults" + }, + { + "key": "host_key_checking", + "section": "ssh_connection", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ], + "type": "boolean", + "vars": [ + { + "name": "ansible_host_key_checking", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + }, + { + "name": "ansible_ssh_host_key_checking", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ] + }, + "password": { + "description": "Authentication password for the C(remote_user). Can be supplied as CLI option.", + "vars": [ + { + "name": "ansible_password" + }, + { + "name": "ansible_ssh_pass" + }, + { + "name": "ansible_ssh_password" + } + ] + }, + "pipelining": { + "default": "ANSIBLE_PIPELINING", + "description": [ + "Pipelining reduces the number of connection operations required to execute a module on the remote server, by executing many Ansible modules without actual file transfers.", + "This can result in a very significant performance improvement when enabled.", + "However this can conflict with privilege escalation (become). For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts, which is why this feature is disabled by default." + ], + "env": [ + { + "name": "ANSIBLE_PIPELINING" + }, + { + "name": "ANSIBLE_SSH_PIPELINING" + } + ], + "ini": [ + { + "key": "pipelining", + "section": "connection" + }, + { + "key": "pipelining", + "section": "ssh_connection" + } + ], + "type": "boolean", + "vars": [ + { + "name": "ansible_pipelining" + }, + { + "name": "ansible_ssh_pipelining" + } + ] + }, + "port": { + "description": "Remote port to connect to.", + "env": [ + { + "name": "ANSIBLE_REMOTE_PORT" + } + ], + "ini": [ + { + "key": "remote_port", + "section": "defaults" + } + ], + "type": "int", + "vars": [ + { + "name": "ansible_port" + }, + { + "name": "ansible_ssh_port" + } + ] + }, + "private_key_file": { + "cli": [ + { + "name": "private_key_file" + } + ], + "description": [ + "Path to private key file to use for authentication" + ], + "env": [ + { + "name": "ANSIBLE_PRIVATE_KEY_FILE" + } + ], + "ini": [ + { + "key": "private_key_file", + "section": "defaults" + } + ], + "vars": [ + { + "name": "ansible_private_key_file" + }, + { + "name": "ansible_ssh_private_key_file" + } + ] + }, + "remote_user": { + "cli": [ + { + "name": "user" + } + ], + "description": [ + "User name with which to login to the remote server, normally set by the remote_user keyword.", + "If no user is supplied, Ansible will let the ssh client binary choose the user as it normally" + ], + "env": [ + { + "name": "ANSIBLE_REMOTE_USER" + } + ], + "ini": [ + { + "key": "remote_user", + "section": "defaults" + } + ], + "vars": [ + { + "name": "ansible_user" + }, + { + "name": "ansible_ssh_user" + } + ] + }, + "retries": { + "default": 3, + "description": "Number of attempts to connect.", + "env": [ + { + "name": "ANSIBLE_SSH_RETRIES" + } + ], + "ini": [ + { + "key": "retries", + "section": "connection" + }, + { + "key": "retries", + "section": "ssh_connection" + } + ], + "type": "integer", + "vars": [ + { + "name": "ansible_ssh_retries", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "scp_executable": { + "default": "scp", + "description": [ + "This defines the location of the scp binary. It defaults to `scp` which will use the first binary available in $PATH." + ], + "env": [ + { + "name": "ANSIBLE_SCP_EXECUTABLE" + } + ], + "ini": [ + { + "key": "scp_executable", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_scp_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.6", + "version_added_collection": "ansible.builtin" + }, + "scp_extra_args": { + "cli": [ + { + "name": "scp_extra_args" + } + ], + "description": "Extra exclusive to the ``scp`` CLI", + "env": [ + { + "name": "ANSIBLE_SCP_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "scp_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "vars": [ + { + "name": "ansible_scp_extra_args" + } + ] + }, + "scp_if_ssh": { + "default": "smart", + "description": [ + "Preferred method to use when transfering files over ssh", + "When set to smart, Ansible will try them until one succeeds or they all fail", + "If set to True, it will force 'scp', if False it will use 'sftp'" + ], + "env": [ + { + "name": "ANSIBLE_SCP_IF_SSH" + } + ], + "ini": [ + { + "key": "scp_if_ssh", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_scp_if_ssh", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "sftp_batch_mode": { + "default": "yes", + "description": "TODO: write it", + "env": [ + { + "name": "ANSIBLE_SFTP_BATCH_MODE" + } + ], + "ini": [ + { + "key": "sftp_batch_mode", + "section": "ssh_connection" + } + ], + "type": "bool", + "vars": [ + { + "name": "ansible_sftp_batch_mode", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "sftp_executable": { + "default": "sftp", + "description": [ + "This defines the location of the sftp binary. It defaults to ``sftp`` which will use the first binary available in $PATH." + ], + "env": [ + { + "name": "ANSIBLE_SFTP_EXECUTABLE" + } + ], + "ini": [ + { + "key": "sftp_executable", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_sftp_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.6", + "version_added_collection": "ansible.builtin" + }, + "sftp_extra_args": { + "cli": [ + { + "name": "sftp_extra_args" + } + ], + "description": "Extra exclusive to the ``sftp`` CLI", + "env": [ + { + "name": "ANSIBLE_SFTP_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "sftp_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "vars": [ + { + "name": "ansible_sftp_extra_args" + } + ] + }, + "ssh_args": { + "cli": [ + { + "name": "ssh_args" + } + ], + "default": "-C -o ControlMaster=auto -o ControlPersist=60s", + "description": "Arguments to pass to all ssh cli tools", + "env": [ + { + "name": "ANSIBLE_SSH_ARGS" + } + ], + "ini": [ + { + "key": "ssh_args", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_ssh_args", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ] + }, + "ssh_common_args": { + "cli": [ + { + "name": "ssh_common_args" + } + ], + "description": "Common extra args for all ssh CLI tools", + "env": [ + { + "name": "ANSIBLE_SSH_COMMON_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "ssh_common_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "vars": [ + { + "name": "ansible_ssh_common_args" + } + ] + }, + "ssh_executable": { + "default": "ssh", + "description": [ + "This defines the location of the ssh binary. It defaults to ``ssh`` which will use the first ssh binary available in $PATH.", + "This option is usually not required, it might be useful when access to system ssh is restricted, or when using ssh wrappers to connect to remote hosts." + ], + "env": [ + { + "name": "ANSIBLE_SSH_EXECUTABLE" + } + ], + "ini": [ + { + "key": "ssh_executable", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_ssh_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.2", + "version_added_collection": "ansible.builtin" + }, + "ssh_extra_args": { + "cli": [ + { + "name": "ssh_extra_args" + } + ], + "description": "Extra exclusive to the 'ssh' CLI", + "env": [ + { + "name": "ANSIBLE_SSH_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "ssh_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "vars": [ + { + "name": "ansible_ssh_extra_args" + } + ] + }, + "ssh_transfer_method": { + "choices": [ + "sftp", + "scp", + "piped", + "smart" + ], + "default": "smart", + "description": [ + "Preferred method to use when transferring files over ssh", + "Setting to 'smart' (default) will try them in order, until one succeeds or they all fail", + "Using 'piped' creates an ssh pipe with ``dd`` on either side to copy the data" + ], + "env": [ + { + "name": "ANSIBLE_SSH_TRANSFER_METHOD" + } + ], + "ini": [ + { + "key": "transfer_method", + "section": "ssh_connection" + } + ] + }, + "sshpass_prompt": { + "default": "", + "description": "Password prompt that sshpass should search for. Supported by sshpass 1.06 and up.", + "env": [ + { + "name": "ANSIBLE_SSHPASS_PROMPT" + } + ], + "ini": [ + { + "key": "sshpass_prompt", + "section": "ssh_connection" + } + ], + "vars": [ + { + "name": "ansible_sshpass_prompt" + } + ], + "version_added": "2.10", + "version_added_collection": "ansible.builtin" + }, + "timeout": { + "cli": [ + { + "name": "timeout" + } + ], + "default": 10, + "description": [ + "This is the default ammount of time we will wait while establishing an ssh connection", + "It also controls how long we can wait to access reading the connection once established (select on the socket)" + ], + "env": [ + { + "name": "ANSIBLE_TIMEOUT" + }, + { + "name": "ANSIBLE_SSH_TIMEOUT", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "key": "timeout", + "section": "defaults" + }, + { + "key": "timeout", + "section": "ssh_connection", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ], + "type": "integer", + "vars": [ + { + "name": "ansible_ssh_timeout", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ] + }, + "use_tty": { + "default": "yes", + "description": "add -tt to ssh commands to force tty allocation", + "env": [ + { + "name": "ANSIBLE_SSH_USETTY" + } + ], + "ini": [ + { + "key": "usetty", + "section": "ssh_connection" + } + ], + "type": "bool", + "vars": [ + { + "name": "ansible_ssh_use_tty", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + }, + "short_description": "connect via ssh client binary", + "version_added": "historical", + "version_added_collection": "ansible.builtin" + }, + "examples": null, + "metadata": null, + "return": null + } +} diff --git a/tests/functional/schema/good_data/ssh_connection_results.json b/tests/functional/schema/good_data/ssh_connection_results.json new file mode 100644 index 00000000..d36f1862 --- /dev/null +++ b/tests/functional/schema/good_data/ssh_connection_results.json @@ -0,0 +1,1168 @@ +{ + "__root__": { + "ansible.builtin.ssh": { + "doc": { + "aliases": [], + "author": [ + "ansible (@core)" + ], + "collection": "ansible.builtin", + "deprecated": {}, + "description": [ + "This connection plugin allows ansible to communicate to the target machines via normal ssh command line.", + "Ansible does not expose a channel to allow communication between the user and the ssh process to accept a password manually to decrypt an ssh key when using this connection plugin (which is the default). The use of ``ssh-agent`` is highly recommended." + ], + "extends_documentation_fragment": [], + "filename": "/srv/ansible/vanilla/lib/ansible/plugins/connection/ssh.py", + "name": "ssh", + "notes": [ + "Many options default to 'None' here but that only means we don't override the ssh tool's defaults and/or configuration. For example, if you specify the port in this plugin it will override any C(Port) entry in your C(.ssh/config)." + ], + "options": { + "control_path": { + "aliases": [], + "choices": [], + "cli": [], + "default": null, + "deprecated": {}, + "description": [ + "This is the location to save ssh's ControlPath sockets, it uses ssh's variable substitution.", + "Since 2.3, if null (default), ansible will generate a unique hash. Use `%(directory)s` to indicate where to use the control dir path setting.", + "Before 2.3 it defaulted to `control_path=%(directory)s/ansible-ssh-%%h-%%p-%%r`.", + "Be aware that this setting is ignored if `-o ControlPath` is set in ssh args." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_CONTROL_PATH", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "control_path", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_control_path", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "control_path_dir": { + "aliases": [], + "choices": [], + "cli": [], + "default": "~/.ansible/cp", + "deprecated": {}, + "description": [ + "This sets the directory to use for ssh control path if the control path setting is null.", + "Also, provides the `%(directory)s` variable for the control path setting." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_CONTROL_PATH_DIR", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "control_path_dir", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_control_path_dir", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "host": { + "aliases": [], + "choices": [], + "cli": [], + "default": null, + "deprecated": {}, + "description": [ + "Hostname/ip to connect to." + ], + "elements": "str", + "env": [], + "ini": [], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "inventory_hostname", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_host", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_host", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "delegated_vars['ansible_host']", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "delegated_vars['ansible_ssh_host']", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "host_key_checking": { + "aliases": [], + "choices": [], + "cli": [], + "default": null, + "deprecated": {}, + "description": [ + "Determines if ssh should check host keys" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_HOST_KEY_CHECKING", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ANSIBLE_SSH_HOST_KEY_CHECKING", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "host_key_checking", + "section": "defaults", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "key": "host_key_checking", + "section": "ssh_connection", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "bool", + "vars": [ + { + "deprecated": {}, + "name": "ansible_host_key_checking", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + }, + { + "deprecated": {}, + "name": "ansible_ssh_host_key_checking", + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "password": { + "aliases": [], + "choices": [], + "cli": [], + "default": null, + "deprecated": {}, + "description": [ + "Authentication password for the C(remote_user). Can be supplied as CLI option." + ], + "elements": "str", + "env": [], + "ini": [], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_password", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_pass", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_password", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "pipelining": { + "aliases": [], + "choices": [], + "cli": [], + "default": "ANSIBLE_PIPELINING", + "deprecated": {}, + "description": [ + "Pipelining reduces the number of connection operations required to execute a module on the remote server, by executing many Ansible modules without actual file transfers.", + "This can result in a very significant performance improvement when enabled.", + "However this can conflict with privilege escalation (become). For example, when using sudo operations you must first disable 'requiretty' in the sudoers file for the target hosts, which is why this feature is disabled by default." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_PIPELINING", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ANSIBLE_SSH_PIPELINING", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "pipelining", + "section": "connection", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "key": "pipelining", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "bool", + "vars": [ + { + "deprecated": {}, + "name": "ansible_pipelining", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_pipelining", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "port": { + "aliases": [], + "choices": [], + "cli": [], + "default": null, + "deprecated": {}, + "description": [ + "Remote port to connect to." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_REMOTE_PORT", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "remote_port", + "section": "defaults", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "int", + "vars": [ + { + "deprecated": {}, + "name": "ansible_port", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_port", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "private_key_file": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "private_key_file", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "Path to private key file to use for authentication" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_PRIVATE_KEY_FILE", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "private_key_file", + "section": "defaults", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_private_key_file", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_private_key_file", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "remote_user": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "user", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "User name with which to login to the remote server, normally set by the remote_user keyword.", + "If no user is supplied, Ansible will let the ssh client binary choose the user as it normally" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_REMOTE_USER", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "remote_user", + "section": "defaults", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_user", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ansible_ssh_user", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "retries": { + "aliases": [], + "choices": [], + "cli": [], + "default": 3, + "deprecated": {}, + "description": [ + "Number of attempts to connect." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_RETRIES", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "retries", + "section": "connection", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "key": "retries", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "int", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_retries", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "scp_executable": { + "aliases": [], + "choices": [], + "cli": [], + "default": "scp", + "deprecated": {}, + "description": [ + "This defines the location of the scp binary. It defaults to `scp` which will use the first binary available in $PATH." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SCP_EXECUTABLE", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "scp_executable", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_scp_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.6", + "version_added_collection": "ansible.builtin" + }, + "scp_extra_args": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "scp_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "Extra exclusive to the ``scp`` CLI" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SCP_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "scp_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_scp_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "scp_if_ssh": { + "aliases": [], + "choices": [], + "cli": [], + "default": "smart", + "deprecated": {}, + "description": [ + "Preferred method to use when transfering files over ssh", + "When set to smart, Ansible will try them until one succeeds or they all fail", + "If set to True, it will force 'scp', if False it will use 'sftp'" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SCP_IF_SSH", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "scp_if_ssh", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_scp_if_ssh", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "sftp_batch_mode": { + "aliases": [], + "choices": [], + "cli": [], + "default": "yes", + "deprecated": {}, + "description": [ + "TODO: write it" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SFTP_BATCH_MODE", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "sftp_batch_mode", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "bool", + "vars": [ + { + "deprecated": {}, + "name": "ansible_sftp_batch_mode", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "sftp_executable": { + "aliases": [], + "choices": [], + "cli": [], + "default": "sftp", + "deprecated": {}, + "description": [ + "This defines the location of the sftp binary. It defaults to ``sftp`` which will use the first binary available in $PATH." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SFTP_EXECUTABLE", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "sftp_executable", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_sftp_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.6", + "version_added_collection": "ansible.builtin" + }, + "sftp_extra_args": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "sftp_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "Extra exclusive to the ``sftp`` CLI" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SFTP_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "sftp_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_sftp_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "ssh_args": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "ssh_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": "-C -o ControlMaster=auto -o ControlPersist=60s", + "deprecated": {}, + "description": [ + "Arguments to pass to all ssh cli tools" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_ARGS", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "ssh_args", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_args", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "ssh_common_args": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "ssh_common_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "Common extra args for all ssh CLI tools" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_COMMON_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "ssh_common_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_common_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "ssh_executable": { + "aliases": [], + "choices": [], + "cli": [], + "default": "ssh", + "deprecated": {}, + "description": [ + "This defines the location of the ssh binary. It defaults to ``ssh`` which will use the first ssh binary available in $PATH.", + "This option is usually not required, it might be useful when access to system ssh is restricted, or when using ssh wrappers to connect to remote hosts." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_EXECUTABLE", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "ssh_executable", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_executable", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.2", + "version_added_collection": "ansible.builtin" + }, + "ssh_extra_args": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "ssh_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": null, + "deprecated": {}, + "description": [ + "Extra exclusive to the 'ssh' CLI" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_EXTRA_ARGS", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "ssh_extra_args", + "section": "ssh_connection", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_extra_args", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "ssh_transfer_method": { + "aliases": [], + "choices": [ + "sftp", + "scp", + "piped", + "smart" + ], + "cli": [], + "default": "smart", + "deprecated": {}, + "description": [ + "Preferred method to use when transferring files over ssh", + "Setting to 'smart' (default) will try them in order, until one succeeds or they all fail", + "Using 'piped' creates an ssh pipe with ``dd`` on either side to copy the data" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_TRANSFER_METHOD", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "transfer_method", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [], + "version_added": "historical", + "version_added_collection": "" + }, + "sshpass_prompt": { + "aliases": [], + "choices": [], + "cli": [], + "default": "", + "deprecated": {}, + "description": [ + "Password prompt that sshpass should search for. Supported by sshpass 1.06 and up." + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSHPASS_PROMPT", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "sshpass_prompt", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "str", + "vars": [ + { + "deprecated": {}, + "name": "ansible_sshpass_prompt", + "version_added": "historical", + "version_added_collection": "" + } + ], + "version_added": "2.10", + "version_added_collection": "ansible.builtin" + }, + "timeout": { + "aliases": [], + "choices": [], + "cli": [ + { + "deprecated": {}, + "name": "timeout", + "version_added": "historical", + "version_added_collection": "" + } + ], + "default": 10, + "deprecated": {}, + "description": [ + "This is the default ammount of time we will wait while establishing an ssh connection", + "It also controls how long we can wait to access reading the connection once established (select on the socket)" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_TIMEOUT", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "name": "ANSIBLE_SSH_TIMEOUT", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "timeout", + "section": "defaults", + "version_added": "historical", + "version_added_collection": "" + }, + { + "deprecated": {}, + "key": "timeout", + "section": "ssh_connection", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ], + "required": false, + "suboptions": {}, + "type": "int", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_timeout", + "version_added": "2.11", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "historical", + "version_added_collection": "" + }, + "use_tty": { + "aliases": [], + "choices": [], + "cli": [], + "default": "yes", + "deprecated": {}, + "description": [ + "add -tt to ssh commands to force tty allocation" + ], + "elements": "str", + "env": [ + { + "deprecated": {}, + "name": "ANSIBLE_SSH_USETTY", + "version_added": "historical", + "version_added_collection": "" + } + ], + "ini": [ + { + "deprecated": {}, + "key": "usetty", + "section": "ssh_connection", + "version_added": "historical", + "version_added_collection": "" + } + ], + "required": false, + "suboptions": {}, + "type": "bool", + "vars": [ + { + "deprecated": {}, + "name": "ansible_ssh_use_tty", + "version_added": "2.7", + "version_added_collection": "ansible.builtin" + } + ], + "version_added": "2.5", + "version_added_collection": "ansible.builtin" + } + }, + "requirements": [], + "seealso": [], + "short_description": "connect via ssh client binary", + "todo": [], + "version_added": "historical", + "version_added_collection": "ansible.builtin" + }, + "examples": "", + "metadata": null, + "return_": {} + } + } +} \ No newline at end of file diff --git a/tests/functional/schema/test_schema.py b/tests/functional/schema/test_schema.py index f362c766..9ba95be5 100644 --- a/tests/functional/schema/test_schema.py +++ b/tests/functional/schema/test_schema.py @@ -10,6 +10,22 @@ from antsibull.schemas import ansible_doc as ad +# To generate the data in the one_*.json files, run:: +# ansible-doc --json -t $PLUGIN_TYPE $PLUGIN_NAME > \ +# tests/functional/schema/good_data/one_$PLUGINTYPE.json +# +# The matching one_$PLUGINTYPE_results.json file is created by running the schema over the +# input, dumping that to one_$PLUGINTYPE_results.json, and then manually inspecting it to +# make sure it is correct. Due to the manual inspection, these might be considered better +# at catching regressions than at detecting errors in fresh code. Some sample python code for +# dumping the file:: +# +# import json +# from antsibull.schemas.ansible_doc import ConnectionPluginSchema +# raw = open('one_connection.json').read() +# normalized = ConnectionPluginSchema.parse_raw(raw) +# out = json.dumps(normalized.dict(), indent=4, sort_keys=True) +# open('one_connection_results.json', 'w').write(out) SINGLE_TESTS = { 'one_become.json': ad.BecomePluginSchema, 'one_cache.json': ad.CachePluginSchema, @@ -46,3 +62,29 @@ def test_one_plugin_of_each_type(test_file, test_schema): model_dict = model.dict() assert model_dict == results + + +def test_ssh_connection(): + """Test using the cli field with the ssh connection.""" + + # The ssh connection plugin is the only one which can take values directly from + # dedicated command line arguments in ansible and ansible-playbook. Make sure that + # we can deal with its documentation to test that the cli field they use for that works. + + test_file = 'ssh_connection.json' + test_schema = ad.ConnectionPluginSchema + + test_dir = os.path.dirname(__file__) + result_file = os.path.join(test_dir, 'good_data', 'ssh_connection_results.json') + full_path = os.path.join(test_dir, 'good_data', test_file) + + with open(result_file, 'r') as f: + results = json.load(f) + + with open(full_path, 'r') as f: + ansible_doc_output = f.read() + + model = test_schema.parse_raw(ansible_doc_output) + + model_dict = model.dict() + assert model_dict == results