docs(schema): Add descriptions for authZ and connector
This commit is contained in:
parent
80cd1350a5
commit
edb91e2e4a
|
@ -339,17 +339,26 @@ fields("cache") ->
|
||||||
{"enable",
|
{"enable",
|
||||||
sc(
|
sc(
|
||||||
boolean(),
|
boolean(),
|
||||||
#{default => true}
|
#{
|
||||||
|
default => true,
|
||||||
|
desc => "Enable or disable the authorization cache."
|
||||||
|
}
|
||||||
)},
|
)},
|
||||||
{"max_size",
|
{"max_size",
|
||||||
sc(
|
sc(
|
||||||
range(1, 1048576),
|
range(1, 1048576),
|
||||||
#{default => 32}
|
#{
|
||||||
|
default => 32,
|
||||||
|
desc => "Maximum number of cached items."
|
||||||
|
}
|
||||||
)},
|
)},
|
||||||
{"ttl",
|
{"ttl",
|
||||||
sc(
|
sc(
|
||||||
duration(),
|
duration(),
|
||||||
#{default => "1m"}
|
#{
|
||||||
|
default => "1m",
|
||||||
|
desc => "Time to live for the cached data."
|
||||||
|
}
|
||||||
)}
|
)}
|
||||||
];
|
];
|
||||||
fields("mqtt") ->
|
fields("mqtt") ->
|
||||||
|
|
|
@ -73,14 +73,17 @@ fields(other_algorithms) ->
|
||||||
{salt_position, fun salt_position/1}].
|
{salt_position, fun salt_position/1}].
|
||||||
|
|
||||||
salt_position(type) -> {enum, [prefix, suffix]};
|
salt_position(type) -> {enum, [prefix, suffix]};
|
||||||
|
salt_position(desc) -> "Specifies whether the password salt is stored as a prefix or the suffix.";
|
||||||
salt_position(default) -> prefix;
|
salt_position(default) -> prefix;
|
||||||
salt_position(_) -> undefined.
|
salt_position(_) -> undefined.
|
||||||
|
|
||||||
salt_rounds(type) -> integer();
|
salt_rounds(type) -> integer();
|
||||||
|
salt_rounds(desc) -> "Cost factor for the bcrypt hash.";
|
||||||
salt_rounds(default) -> 10;
|
salt_rounds(default) -> 10;
|
||||||
salt_rounds(_) -> undefined.
|
salt_rounds(_) -> undefined.
|
||||||
|
|
||||||
dk_length(type) -> integer();
|
dk_length(type) -> integer();
|
||||||
|
dk_length(desc) -> "Length of the derived key.";
|
||||||
dk_length(required) -> false;
|
dk_length(required) -> false;
|
||||||
dk_length(_) -> undefined.
|
dk_length(_) -> undefined.
|
||||||
|
|
||||||
|
|
|
@ -55,11 +55,15 @@ root_type() ->
|
||||||
|
|
||||||
mechanism(Name) ->
|
mechanism(Name) ->
|
||||||
hoconsc:mk(hoconsc:enum([Name]),
|
hoconsc:mk(hoconsc:enum([Name]),
|
||||||
#{required => true}).
|
#{ required => true
|
||||||
|
, desc => "Authentication mechanism."
|
||||||
|
}).
|
||||||
|
|
||||||
backend(Name) ->
|
backend(Name) ->
|
||||||
hoconsc:mk(hoconsc:enum([Name]),
|
hoconsc:mk(hoconsc:enum([Name]),
|
||||||
#{required => true}).
|
#{ required => true
|
||||||
|
, desc => "Backend type."
|
||||||
|
}).
|
||||||
|
|
||||||
fields("metrics_status_fields") ->
|
fields("metrics_status_fields") ->
|
||||||
[ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})}
|
[ {"metrics", mk(ref(?MODULE, "metrics"), #{desc => "The metrics of the resource"})}
|
||||||
|
@ -89,7 +93,7 @@ fields("node_metrics") ->
|
||||||
|
|
||||||
fields("node_status") ->
|
fields("node_status") ->
|
||||||
[ node_name()
|
[ node_name()
|
||||||
, {"status", mk(status(), #{})}
|
, {"status", mk(status(), #{desc => "Status of the node."})}
|
||||||
].
|
].
|
||||||
|
|
||||||
status() ->
|
status() ->
|
||||||
|
|
|
@ -26,6 +26,7 @@
|
||||||
-export([ namespace/0
|
-export([ namespace/0
|
||||||
, roots/0
|
, roots/0
|
||||||
, fields/1
|
, fields/1
|
||||||
|
, desc/1
|
||||||
]).
|
]).
|
||||||
|
|
||||||
-export([ refs/0
|
-export([ refs/0
|
||||||
|
@ -55,6 +56,15 @@ fields('replica-set') ->
|
||||||
fields('sharded-cluster') ->
|
fields('sharded-cluster') ->
|
||||||
common_fields() ++ emqx_connector_mongo:fields(sharded).
|
common_fields() ++ emqx_connector_mongo:fields(sharded).
|
||||||
|
|
||||||
|
desc(standalone) ->
|
||||||
|
"Configuration for a standalone MongoDB instance.";
|
||||||
|
desc('replica-set') ->
|
||||||
|
"Configuration for a replica set.";
|
||||||
|
desc('sharded-cluster') ->
|
||||||
|
"Configuration for a sharded cluster.";
|
||||||
|
desc(_) ->
|
||||||
|
undefined.
|
||||||
|
|
||||||
common_fields() ->
|
common_fields() ->
|
||||||
[ {mechanism, emqx_authn_schema:mechanism('password_based')}
|
[ {mechanism, emqx_authn_schema:mechanism('password_based')}
|
||||||
, {backend, emqx_authn_schema:backend(mongodb)}
|
, {backend, emqx_authn_schema:backend(mongodb)}
|
||||||
|
@ -67,19 +77,27 @@ common_fields() ->
|
||||||
] ++ emqx_authn_schema:common_fields().
|
] ++ emqx_authn_schema:common_fields().
|
||||||
|
|
||||||
collection(type) -> binary();
|
collection(type) -> binary();
|
||||||
|
collection(desc) -> "Collection used to store authentication data.";
|
||||||
collection(_) -> undefined.
|
collection(_) -> undefined.
|
||||||
|
|
||||||
selector(type) -> map();
|
selector(type) -> map();
|
||||||
|
selector(desc) -> "Statement that is executed during the authentication process. "
|
||||||
|
"Commands can support following wildcards:\n"
|
||||||
|
" - `${username}`: substituted with client's username\n"
|
||||||
|
" - `${clientid}`: substituted with the clientid";
|
||||||
selector(_) -> undefined.
|
selector(_) -> undefined.
|
||||||
|
|
||||||
password_hash_field(type) -> binary();
|
password_hash_field(type) -> binary();
|
||||||
|
password_hash_field(desc) -> "Document field that contains password hash.";
|
||||||
password_hash_field(_) -> undefined.
|
password_hash_field(_) -> undefined.
|
||||||
|
|
||||||
salt_field(type) -> binary();
|
salt_field(type) -> binary();
|
||||||
|
salt_field(desc) -> "Document field that contains the password salt.";
|
||||||
salt_field(required) -> false;
|
salt_field(required) -> false;
|
||||||
salt_field(_) -> undefined.
|
salt_field(_) -> undefined.
|
||||||
|
|
||||||
is_superuser_field(type) -> binary();
|
is_superuser_field(type) -> binary();
|
||||||
|
is_superuser_field(desc) -> "Document field that defines if the user has superuser privileges.";
|
||||||
is_superuser_field(required) -> false;
|
is_superuser_field(required) -> false;
|
||||||
is_superuser_field(_) -> undefined.
|
is_superuser_field(_) -> undefined.
|
||||||
|
|
||||||
|
|
|
@ -66,7 +66,7 @@ fields("authorization") ->
|
||||||
]),
|
]),
|
||||||
default => [],
|
default => [],
|
||||||
desc =>
|
desc =>
|
||||||
"""
|
"
|
||||||
Authorization data sources.<br>
|
Authorization data sources.<br>
|
||||||
An array of authorization (ACL) data providers.
|
An array of authorization (ACL) data providers.
|
||||||
It is designed as an array, not a hash-map, so the sources can be
|
It is designed as an array, not a hash-map, so the sources can be
|
||||||
|
@ -84,7 +84,7 @@ the default action configured in 'authorization.no_match' is applied.<br>
|
||||||
NOTE:
|
NOTE:
|
||||||
The source elements are identified by their 'type'.
|
The source elements are identified by their 'type'.
|
||||||
It is NOT allowed to configure two or more sources of the same type.
|
It is NOT allowed to configure two or more sources of the same type.
|
||||||
"""
|
"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
];
|
];
|
||||||
|
@ -94,7 +94,7 @@ fields(file) ->
|
||||||
default => true}}
|
default => true}}
|
||||||
, {path, #{type => string(),
|
, {path, #{type => string(),
|
||||||
required => true,
|
required => true,
|
||||||
desc => """
|
desc => "
|
||||||
Path to the file which contains the ACL rules.<br>
|
Path to the file which contains the ACL rules.<br>
|
||||||
If the file provisioned before starting EMQX node,
|
If the file provisioned before starting EMQX node,
|
||||||
it can be placed anywhere as long as EMQX has read access to it.
|
it can be placed anywhere as long as EMQX has read access to it.
|
||||||
|
@ -102,7 +102,7 @@ it can be placed anywhere as long as EMQX has read access to it.
|
||||||
In case the rule-set is created from EMQX dashboard or management API,
|
In case the rule-set is created from EMQX dashboard or management API,
|
||||||
the file will be placed in `authz` subdirectory inside EMQX's `data_dir`,
|
the file will be placed in `authz` subdirectory inside EMQX's `data_dir`,
|
||||||
and the new rules will override all rules from the old config file.
|
and the new rules will override all rules from the old config file.
|
||||||
"""
|
"
|
||||||
}}
|
}}
|
||||||
];
|
];
|
||||||
fields(http_get) ->
|
fields(http_get) ->
|
||||||
|
@ -152,11 +152,12 @@ http_common_fields() ->
|
||||||
maps:from_list(connector_fields(http)))).
|
maps:from_list(connector_fields(http)))).
|
||||||
|
|
||||||
mongo_common_fields() ->
|
mongo_common_fields() ->
|
||||||
[ {collection, #{type => atom()}}
|
[ {collection, #{type => atom(), desc => "`MongoDB` collection containing the authorization data."}}
|
||||||
, {selector, #{type => map()}}
|
, {selector, #{type => map(), desc => "MQL query used to select the authorization record."}}
|
||||||
, {type, #{type => mongodb}}
|
, {type, #{type => mongodb, desc => "Database backend."}}
|
||||||
, {enable, #{type => boolean(),
|
, {enable, #{type => boolean(),
|
||||||
default => true}}
|
default => true,
|
||||||
|
desc => "Enable or disable the backend."}}
|
||||||
].
|
].
|
||||||
|
|
||||||
validations() ->
|
validations() ->
|
||||||
|
@ -244,6 +245,7 @@ union_array(Item) when is_list(Item) ->
|
||||||
|
|
||||||
query() ->
|
query() ->
|
||||||
#{type => binary(),
|
#{type => binary(),
|
||||||
|
desc => "",
|
||||||
validator => fun(S) ->
|
validator => fun(S) ->
|
||||||
case size(S) > 0 of
|
case size(S) > 0 of
|
||||||
true -> ok;
|
true -> ok;
|
||||||
|
@ -264,9 +266,10 @@ connector_fields(DB, Fields) ->
|
||||||
error:Reason ->
|
error:Reason ->
|
||||||
erlang:error(Reason)
|
erlang:error(Reason)
|
||||||
end,
|
end,
|
||||||
[ {type, #{type => DB}}
|
[ {type, #{type => DB, desc => "Database backend."}}
|
||||||
, {enable, #{type => boolean(),
|
, {enable, #{type => boolean(),
|
||||||
default => true}}
|
default => true,
|
||||||
|
desc => "Enable or disable the backend."}}
|
||||||
] ++ erlang:apply(Mod, fields, [Fields]).
|
] ++ erlang:apply(Mod, fields, [Fields]).
|
||||||
|
|
||||||
to_list(A) when is_atom(A) ->
|
to_list(A) when is_atom(A) ->
|
||||||
|
|
|
@ -54,13 +54,15 @@ roots() ->
|
||||||
|
|
||||||
fields(single) ->
|
fields(single) ->
|
||||||
[ {mongo_type, #{type => single,
|
[ {mongo_type, #{type => single,
|
||||||
default => single}}
|
default => single,
|
||||||
|
desc => "Standalone instance."}}
|
||||||
, {server, fun server/1}
|
, {server, fun server/1}
|
||||||
, {w_mode, fun w_mode/1}
|
, {w_mode, fun w_mode/1}
|
||||||
] ++ mongo_fields();
|
] ++ mongo_fields();
|
||||||
fields(rs) ->
|
fields(rs) ->
|
||||||
[ {mongo_type, #{type => rs,
|
[ {mongo_type, #{type => rs,
|
||||||
default => rs}}
|
default => rs,
|
||||||
|
desc => "Replica set."}}
|
||||||
, {servers, fun servers/1}
|
, {servers, fun servers/1}
|
||||||
, {w_mode, fun w_mode/1}
|
, {w_mode, fun w_mode/1}
|
||||||
, {r_mode, fun r_mode/1}
|
, {r_mode, fun r_mode/1}
|
||||||
|
@ -68,7 +70,8 @@ fields(rs) ->
|
||||||
] ++ mongo_fields();
|
] ++ mongo_fields();
|
||||||
fields(sharded) ->
|
fields(sharded) ->
|
||||||
[ {mongo_type, #{type => sharded,
|
[ {mongo_type, #{type => sharded,
|
||||||
default => sharded}}
|
default => sharded,
|
||||||
|
desc => "Sharded cluster."}}
|
||||||
, {servers, fun servers/1}
|
, {servers, fun servers/1}
|
||||||
, {w_mode, fun w_mode/1}
|
, {w_mode, fun w_mode/1}
|
||||||
] ++ mongo_fields();
|
] ++ mongo_fields();
|
||||||
|
@ -306,22 +309,27 @@ servers(desc) -> ?SERVERS_DESC ++ server(desc);
|
||||||
servers(_) -> undefined.
|
servers(_) -> undefined.
|
||||||
|
|
||||||
w_mode(type) -> hoconsc:enum([unsafe, safe]);
|
w_mode(type) -> hoconsc:enum([unsafe, safe]);
|
||||||
|
w_mode(desc) -> "Write mode.";
|
||||||
w_mode(default) -> unsafe;
|
w_mode(default) -> unsafe;
|
||||||
w_mode(_) -> undefined.
|
w_mode(_) -> undefined.
|
||||||
|
|
||||||
r_mode(type) -> hoconsc:enum([master, slave_ok]);
|
r_mode(type) -> hoconsc:enum([master, slave_ok]);
|
||||||
|
r_mode(desc) -> "Read mode.";
|
||||||
r_mode(default) -> master;
|
r_mode(default) -> master;
|
||||||
r_mode(_) -> undefined.
|
r_mode(_) -> undefined.
|
||||||
|
|
||||||
duration(type) -> emqx_schema:duration_ms();
|
duration(type) -> emqx_schema:duration_ms();
|
||||||
|
duration(desc) -> "Time interval, such as timeout or TTL.";
|
||||||
duration(required) -> false;
|
duration(required) -> false;
|
||||||
duration(_) -> undefined.
|
duration(_) -> undefined.
|
||||||
|
|
||||||
replica_set_name(type) -> binary();
|
replica_set_name(type) -> binary();
|
||||||
|
replica_set_name(desc) -> "Name of the replica set.";
|
||||||
replica_set_name(required) -> false;
|
replica_set_name(required) -> false;
|
||||||
replica_set_name(_) -> undefined.
|
replica_set_name(_) -> undefined.
|
||||||
|
|
||||||
srv_record(type) -> boolean();
|
srv_record(type) -> boolean();
|
||||||
|
srv_record(desc) -> "Use DNS SRV record.";
|
||||||
srv_record(default) -> false;
|
srv_record(default) -> false;
|
||||||
srv_record(_) -> undefined.
|
srv_record(_) -> undefined.
|
||||||
|
|
||||||
|
|
|
@ -52,7 +52,8 @@ fields(_) -> [].
|
||||||
|
|
||||||
ssl_fields() ->
|
ssl_fields() ->
|
||||||
[ {ssl, #{type => hoconsc:ref(emqx_schema, ssl_client_opts),
|
[ {ssl, #{type => hoconsc:ref(emqx_schema, ssl_client_opts),
|
||||||
default => #{<<"enable">> => false}
|
default => #{<<"enable">> => false},
|
||||||
|
desc => "SSL connection settings."
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
].
|
].
|
||||||
|
@ -66,24 +67,29 @@ relational_db_fields() ->
|
||||||
].
|
].
|
||||||
|
|
||||||
database(type) -> binary();
|
database(type) -> binary();
|
||||||
|
database(desc) -> "Database name.";
|
||||||
database(required) -> true;
|
database(required) -> true;
|
||||||
database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")];
|
database(validator) -> [?NOT_EMPTY("the value of the field 'database' cannot be empty")];
|
||||||
database(_) -> undefined.
|
database(_) -> undefined.
|
||||||
|
|
||||||
pool_size(type) -> integer();
|
pool_size(type) -> integer();
|
||||||
|
pool_size(desc) -> "Size of the connection pool.";
|
||||||
pool_size(default) -> 8;
|
pool_size(default) -> 8;
|
||||||
pool_size(validator) -> [?MIN(1)];
|
pool_size(validator) -> [?MIN(1)];
|
||||||
pool_size(_) -> undefined.
|
pool_size(_) -> undefined.
|
||||||
|
|
||||||
username(type) -> binary();
|
username(type) -> binary();
|
||||||
|
username(desc) -> "EMQX's username in the external database.";
|
||||||
username(required) -> false;
|
username(required) -> false;
|
||||||
username(_) -> undefined.
|
username(_) -> undefined.
|
||||||
|
|
||||||
password(type) -> binary();
|
password(type) -> binary();
|
||||||
|
password(desc) -> "EMQX's password in the external database.";
|
||||||
password(required) -> false;
|
password(required) -> false;
|
||||||
password(_) -> undefined.
|
password(_) -> undefined.
|
||||||
|
|
||||||
auto_reconnect(type) -> boolean();
|
auto_reconnect(type) -> boolean();
|
||||||
|
auto_reconnect(desc) -> "Enable automatic reconnect to the database.";
|
||||||
auto_reconnect(default) -> true;
|
auto_reconnect(default) -> true;
|
||||||
auto_reconnect(_) -> undefined.
|
auto_reconnect(_) -> undefined.
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue