ct_netconfc

模块

ct_netconfc

模块摘要

NETCONF客户端模块。

描述

NETCONF客户端模块。

NETCONF客户端符合RFC 4741 NETCONF配置协议和RFC 4742使用NETCONF安全外壳配置协议（SSH）。

连接到NETCONF服务器

NETCONF会话可以通过一个单一的调用来打开open/1,2或通过调用connect/1,2后面跟着一个或多个呼叫session/1,2,3。

会话的属性将完全相同，除了使用时connect/1,2，您可以通过相同的SSH连接启动多个会话。每个会话都是作为SSH通道实现的。

open/1,2将与一个实施一个NETCONF会话的SSH通道建立一个SSH连接。您可以通过open/1,2多次调用启动多个会话，但是会为每个会话建立一个新的SSH连接。

对于要测试的每个服务器，可以将以下条目添加到配置文件中：

{server_id(),options()}.

server_id()或与其相关的ct:target_name()必须然后到调用中使用connect/2或open/2。

如果服务器不存在任何配置，请使用connect/1或open/1替代，并指定Options参数中的所有必需选项。

记录

NETCONF服务器error_logger用于记录NETCONF流量。一个特殊目的的错误处理程序被实现在ct_conn_log_h。要使用此错误处理程序，请cth_conn_log在测试套件中添加挂钩，例如：

suite() ->
   [{ct_hooks, [{cth_conn_log, [{ct:conn_log_mod(),ct:conn_log_options()}]}]}].

conn_log_mod()是Common Test实现连接协议的模块的名称，例如ct_netconfc。

Hook选项log_type指定记录的类型：

raw

发送和接收的NETCONF数据以“as if”格式记录到单独的文本文件中，无需格式化。该文件的链接被添加到测试用例HTML日志中。

pretty

发送和接收的NETCONF数据被记录到一个单独的文本文件中，XML数据很好地缩进。该文件的链接被添加到测试用例HTML日志中。

html (default)

发送和接收的NETCONF通信量直接打印在测试用例HTML日志中。

silent

未记录NETCONF通信量。

默认情况下，所有NETCONF流量都记录在一个日志文件中。但是，不同的连接可以记录在单独的文件中。为此，请使用hook选项hosts并列出要在套件中使用的服务器/连接的名称。连接必须被命名才能工作，也就是说，它们必须打开open/2。

hosts如果log_type设置为html或，选项不起作用silent。

还可以在配置文件中指定带有配置变量的钩子选项。ct_conn_log*

{ct_conn_log,[{ct:conn_log_mod(),ct:conn_log_options()}]}.

例如：

{ct_conn_log,[{ct_netconfc,[{log_type,pretty},
                            {hosts,[ct:key_or_name()]}]}]}

注

在配置文件中指定的钩子选项会覆盖测试套件中的硬编码钩子选项。

日志示例1：

以下ct_hooks语句导致相当打印NETCONF流量来分隔名为nc_server1和的连接的日志nc_server2。任何其他连接都会记录到默认的NETCONF日志中。

suite() ->
   [{ct_hooks, [{cth_conn_log, [{ct_netconfc,[{log_type,pretty}},
                                              {hosts,[nc_server1,nc_server2]}]}
                               ]}]}].

必须按以下方式打开连接：

open(nc_server1,[...]),
open(nc_server2,[...]).

日志示例2：

以下配置文件将所有NETCONF通信量的原始日志记录到一个文本文件中：

{ct_conn_log,[{ct_netconfc,[{log_type,raw}]}]}.

大ct_hooks语句必须如下所示：

suite() ->
   [{ct_hooks, [{cth_conn_log, []}]}].

同ct_hooks没有配置文件的语句将导致所有NETCONF连接的HTML日志记录到测试用例HTML日志中。

通知

NETCONF客户端还兼容RFC 5277 NETCONF事件通知，后者为NETCONF协议定义了异步消息通知传递服务的机制。

支持这个的具体功能是create_subscription/1-6和get_event_streams/1-3。

默认超时

该模块中的大多数功能都有一个带Timeout参数的变量，另一个没有。如果没有指定其他值，infinity则在Timeout未给出参数时使用默认值。

数据类型

client() =handle()|server_id()|ct:target_name()

error_reason() = term()

event_time() = {eventTime,xml_attributes(), [xs_datetime()]}

handle()

连接到NETCONF服务器或NETCONF会话的不透明引用。

host() = inet:hostname() | inet:ip_address()

netconf_db() = running | startup | candidate

notification() =

{notification,xml_attributes(),notification_content()}

notification_content() = [event_time()|simple_xml()]

option() =

{ssh,host()} |

{port, inet:port_number()} |

{user, string()} |

{password, string()} |

{user_dir, string()} |

{timeout, timeout()}

SshConnectOption是任何有效的选项ssh:connect/3,4。常用的选项是user，password和user_dir。将SshConnectOptions通过SSH应用verfied。

options() = [option()]

用于设置到NETCONF服务器的SSH连接的选项。

server_id() = atom()

服务器的标识，在配置文件中指定。

simple_xml() =

{xml_tag(),xml_attributes(),xml_content()} |

{xml_tag(),xml_content()} |

xml_tag()

这种类型在应用中进一步描述xmerl。

stream_data() =

{description, string()} |

{replaySupport, string()} |

{replayLogCreationTime, string()} |

{replayLogAgedTime, string()}

有关字符串值的数据格式的详细信息，请参阅RFC 5277中的“事件通知的XMLSchema”。

stream_name() = string()

streams() = [{stream_name(), [stream_data()]}]

xml_attribute_tag() = atom()

xml_attribute_value() = string()

xml_attributes() =

[{xml_attribute_tag(),xml_attribute_value()}]

xml_content() = [simple_xml()| iolist()]

xml_tag() = atom()

xpath() = {xpath, string()}

xs_datetime() = string()

此日期和时间标识符具有与xml类型相同的格式。dateTime并符合RFC 3339的日期和时间在互联网上的时间戳。格式如下：

[-]CCYY-MM-DDThh:mm:ss[.s][Z|(+|-)hh:mm]

输出

action(Client, Action) -> Result

action(Client, Action, Timeout) -> Result

类型

执行一个动作。如果返回类型是void，ok则返回而不是{ok,[simple_xml()]}。

close_session(Client) -> Result

close_session(Client, Timeout) -> Result

类型

请求与客户端关联的会话的优雅终止。

当NETCONF服务器收到close-session请求时，它会优雅地关闭会话。服务器释放与会话关联的所有锁和资源，并优雅地关闭任何相关连接。之后收到的任何NETCONF请求close-session请求被忽略。

connect(Options) -> Result

类型

打开到NETCONF服务器的SSH连接。

如果在配置文件中指定了服务器选项，请使用connect/2相反。

handle()通过此连接打开会话时，需要从此函数返回的不透明引用作为连接标识符，请参阅session/1,2,3。

timeout设置SSH连接时使用选项（毫秒）。它在连接的生命周期内不用于任何其他目的。

connect(KeyOrName, ExtraOptions) -> Result

类型

打开到指定NETCONF服务器的SSH连接。

如果KeyOrName是已配置server_id()或target_name()与此类ID相关联，则从配置文件中获取此服务器的选项。

参数ExtraOptions被添加到配置文件中的选项中。如果指定了相同的选项，则会覆盖配置文件中的值ExtraOptions。

如果未在配置文件中指定服务器，请使用connect/1相反。

handle()从此函数返回的不透明引用可以在通过此连接打开会话时用作连接标识符，请参阅session/1,2,3。但是，如果KeyOrName是 target_name()，也就是说，如果服务器是通过调用ct:require/2或命名require测试套件中的语句来命名的，则可以使用该名称来代替handle()。

timeout设置SSH连接时使用选项（毫秒）。它在连接的生命周期内不用于任何其他目的。

copy_config(Client, Target, Source) -> Result

copy_config(Client, Target, Source, Timeout) -> Result

类型

复制配置数据。

可以发布哪些源和目标选项取决于服务器支持的功能。也就是说，:candidate和/或是:startup必需的。

create_subscription(Client) -> Resultcreate_subscription(Client, Stream) -> Resultcreate_subscription(Client, Stream, Filter) -> Resultcreate_subscription(Client, Stream, Filter, Timeout) -> Result

create_subscription(Client, Stream, Filter, StartTime, StopTime) ->

结果

create_subscription(Client,

Stream,

过滤器，

开始时间，

停止时间，

Timeout) ->

结果

类型

为事件通知创建订阅。

此函数为指定的流类型的NETCONF事件通知设置订阅，匹配指定的过滤器。调用进程接收通知作为类型的消息notification()。

上面只显示了一部分功能子句。输入参数的全套有效组合如下：

create_subscription(Client)

create_subscription(Client, Timeout)
create_subscription(Client, Stream)
create_subscription(Client, Filter)

create_subscription(Client, Stream, Timeout)
create_subscription(Client, Filter, Timeout)
create_subscription(Client, Stream, Filter)
create_subscription(Client, StartTime, StopTime)

create_subscription(Client, Stream, Filter, Timeout)
create_subscription(Client, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, StartTime, StopTime)
create_subscription(Client, Filter, StartTime, StopTime)

create_subscription(Client, Stream, StartTime, StopTime, Timeout)
create_subscription(Client, Stream, Filter, StartTime, StopTime)
create_subscription(Client, Stream, Filter, StartTime, StopTime, Timeout)

Stream

可选参数，该参数指示感兴趣的事件流。如果不存在，则发送默认NETCONF流中的事件。

Filter

可选参数，该参数指示所有可能事件的哪个子集感兴趣。参数格式与NETCONF协议操作中的筛选器参数的格式相同。如果不存在，则发送其他参数未阻止的所有事件。

StartTime

可选参数，用于触发重播功能，并指示重播将在指定的时间开始。如果StartTime不存在，这不是重放订阅。

指定比当前时间晚的开始时间是无效的。如果StartTime指定的时间早于日志所能支持的时间，则重播以最早可用的通知开始。

这个参数是类型的。dateTime并符合RFC 3339。实现必须支持时区。

StopTime

可选参数与可选重播功能一起使用，以指示最新的感兴趣的通知。如果StopTime不存在时，通知将一直持续到订阅终止为止。

必须与并一起使用并且晚于StartTime。StopTime在未来的值是有效的。此参数是类型dateTime并符合RFC 3339.实现必须支持时区。

有关事件通知机制的详细信息，请参阅RFC 5277。

delete_config(Client, Target) -> Result

delete_config(Client, Target, Timeout) -> Result

类型

删除配置数据。

正在运行的配置不能删除，:candidate或者:startup必须由服务器通告。

disconnect(Conn) -> ok | {error, error_reason()}

类型

关闭给定的SSH连接。

如果在连接上有开放的NETCONF会话，这些会话将被残酷地中止。若要避免这种情况，请使用close_session/1,2

edit_config(Client, Target, Config) -> Result

edit_config(Client, Target, Config, OptParams) -> Result

edit_config(Client, Target, Config, Timeout) -> Result

edit_config(Client, Target, Config, OptParams, Timeout) -> Result

类型

编辑配置数据。

默认情况下，只有正在运行的目标可用，除非服务器包括:candidate或:startup在它的功能列表中。

OptParams可用于指定可选的参数（default-operation，test-option，或error-option）被添加到所述edit-config请求。该值必须是包含有效简单XML的列表，例如：

[{'default-operation', ["none"]},
 {'error-option', ["rollback-on-error"]}]

如果OptParams没有给出，[]则使用默认值。

get(Client, Filter) -> Result

get(Client, Filter, Timeout) -> Result

类型

获取数据。

该操作从服务器返回配置和状态数据。

过滤器类型xpath只能在服务器支持时使用:xpath。

get_capabilities(Client) -> Result

get_capabilities(Client, Timeout) -> Result

类型

返回服务器端功能。

可以返回RFC 4741 NETCONF配置协议中定义的下列功能标识符：

"urn:ietf:params:netconf:base:1.0"

"urn:ietf:params:netconf:capability:writable-running:1.0"

"urn:ietf:params:netconf:capability:candidate:1.0"

"urn:ietf:params:netconf:capability:confirmed-commit:1.0"

"urn:ietf:params:netconf:capability:rollback-on-error:1.0"

"urn:ietf:params:netconf:capability:startup:1.0"

"urn:ietf:params:netconf:capability:url:1.0"

"urn:ietf:params:netconf:capability:xpath:1.0"

可以存在更多标识符，例如服务器端名称空间。

get_config(Client, Source, Filter) -> Result

get_config(Client, Source, Filter, Timeout) -> Result

类型

获取配置数据。

为了能够访问另一个来源running，服务器必须做广告:candidate和/或:startup。

过滤器类型xpath只能在服务器支持时使用:xpath。

get_event_streams(Client) -> Result

get_event_streams(Client, Timeout) -> Result

get_event_streams(Client, Streams) -> Result

get_event_streams(Client, Streams, Timeout) -> Result

类型

发送获取指定事件流的请求。

Streams是流名称的列表。以下过滤器在get请求中发送到NETCONF服务器：

<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
  <streams>
    <stream>
      <name>StreamName1</name>
    </stream>
    <stream>
      <name>StreamName2</name>
    </stream>
    ...
  </streams>
</netconf>

如果Streams是一个空列表，全通过发送以下筛选器请求流：

<netconf xmlns="urn:ietf:params:xml:ns:netmod:notification">
  <streams/>
</netconf>

如果需要更复杂的过滤，请ct_netconfc:get/2,3根据RFC 5277中的“用于事件通知的XML模式” 使用并指定确切的过滤器。

get_session_id(Client) -> Result

get_session_id(Client, Timeout) -> Result

类型

返回与指定客户端关联的会话ID。

hello(Client) -> Result

hello(Client, Timeout) -> Result

hello(Client, Options, Timeout) -> Result

类型

hello与服务器交换消息。

添加可选功能并向hello服务器发送消息并等待返回。

hello(Client, Options, Timeout) -> Result

kill_session(Client, SessionId, Timeout) -> Result

类型

强制终止与提供的会话Id相关联的会话。

服务器端必须中止任何正在进行的操作，释放与会话相关的锁和资源，并关闭任何关联的连接。

只有当服务器处于确认提交阶段时，配置才会恢复到其进入已确认提交阶段之前的状态。否则，不执行配置回滚。

如果指定的SessionId值等于当前会话ID，则返回错误。

lock(Client, Target) -> Result

lock(Client, Target, Timeout) -> Result

类型

锁定配置目标。

可以使用哪些目标参数取决于服务器是否支持:candidate和/或:startup受支持。如果成功，设备的配置系统对其他客户端（NETCONF，CORBA，SNMP等）不可用。锁意图是短暂的。

操作kill_session/2,3可以用来强制释放另一个NETCONF会话拥有的锁。服务器端如何实现这一点是特定于实现的。

only_open(Options) -> Result

类型

打开一个NETCONF会话，但不发送hello。

作为open/1，但不发送hello消息。

only_open(KeyOrName, ExtraOptions) -> Result

类型

打开一个命名的NETCONF会话，但不发送hello。

作为open/2，但不发送hello消息。

open(Options) -> Result

类型

打开NETCONF会话并交换hello消息。

如果在配置文件中指定了服务器选项，或者为了记录目的需要命名客户端（请参阅Logging本模块中的部分），请open/2改为使用。

handle()在调用此模块中的任何其他功能时，需要从此函数返回的不透明引用作为客户端标识符。

timeout在设置SSH连接和等待hello来自服务器的消息时使用选项（毫秒）。它在连接的生命周期内不用于任何其他目的。

open(KeyOrName, ExtraOptions) -> Result

类型

打开一个命名的NETCONF会话并交换hello消息。

如果KeyOrName是已配置server_id()或target_name()与此类ID相关联，则从配置文件中获取此服务器的选项。

参数ExtraOptions被添加到配置文件中的选项中。如果指定了相同的选项，则会覆盖配置文件中的值ExtraOptions。

如果未在配置文件中指定服务器，请使用open/1相反。

handle()当调用此模块中的任何其他功能时，从此函数返回的不透明引用可用作客户端标识符。但是，如果KeyOrName是a target_name()，也就是说，如果服务器是通过调用ct:require/2或命名require测试套件中的语句来命名的，则可以使用该名称来代替handle()。

timeout在设置SSH连接和等待hello来自服务器的消息时使用选项（毫秒）。它在连接的生命周期内不用于任何其他目的。

另见ct:require/2。

send(Client, SimpleXml) -> Result

send(Client, SimpleXml, Timeout) -> Result

类型

向服务器发送XML文档。

指定的XML文档“as if”发送到服务器。此功能可用于发送本模块中其他界面功能无法表达的XML文档。

send_rpc(Client, SimpleXml) -> Result

send_rpc(Client, SimpleXml, Timeout) -> Result

类型

发送一个NETCONFrpc请求服务器。

指定的XML文档包装在有效的NETCONF rpc请求中并发送到服务器。在message-id和命名空间属性添加到元素rpc。

此功能可用于发送rpc本模块中其他接口功能无法表达的请求。

session(Conn) -> Result

session(Conn, Options) -> Result

session(KeyOrName, Conn) -> Result

类型

在给定的SSH连接上打开NETCONF会话作为通道，并与服务器交换hello消息。

handle()当调用此模块中的任何其他功能时，从此函数返回的不透明引用可用作客户端标识符。然而，如果KeyOrName被使用并且它是a target_name()，那么，如果服务器是通过调用ct:require/2或者require测试套件中的语句来命名的，那么可以使用这个名称来代替handle()。

unlock(Client, Target) -> Result

unlock(Client, Target, Timeout) -> Result

类型

解锁配置目标。

如果客户较早已获得锁定lock/2,3，则此操作会释放关联的锁。要访问另一个目标running，服务器必须支持:candidate和/或:startup。