View source for OPC UA Client Application Operations in OpcCmd

[[Category:GDS]] [[Category:OPC UA]] [[Category:OPC UA discovery]] [[Category:OpcCmd Utility]] [[Category:Tools and Online Services]] 
For general information about the OpcCmd tool, see [[:Category:OpcCmd Utility]].
= Tutorial =
If you execute the commands listed in the tutorial below, you will get an overview of available client application operations.

This tutorial works with the OPC UA Global Discovery Server (GDS) made public by us on the Internet for demo purposes. You should be able to use the same tutorial with your own GDS, by modifying the server URL and user authentication data in the commands, as needed for your GDS.


# Start the OpcCmd utility in interactive mode. The interactive mode is always in effect e.g. when you use ClickOnce, or when running the utility from QuickOPC Launcher/Start menu. In other cases, you need to use the <code>-i</code> (or <code>--interactive</code>) option on the command line.<br/><br/>
# At the {{Style=label|OpcCmd>}} prompt, enter {{Style=keyboard|uaApplication}}, or shortened: {{Style=keyboard|uaapp}}.<ref>Alternatively, you can use <code>uaClient getService uaClientServerApplication</code>.</ref><br/>The program responds with the name of the client application (""OPC Command-line Tool"), which will be used for registrations to GDS. If this is the first time the program is run, it also (silently) creates its self-signed client certificate.<br/><br/>All following commands are entered at the {{Style=label|uaApplication>}} prompt. You can enter <code>-?</code>, <code>-h</code> or <code>--help</code> (possibly preceded by the command name) at any time to obtain help for this prompt (or its commands).<br/><br/>
# In order to create application registration in the GDS, enter {{Style=keyboard|registerToGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>registerToGds</code> can be shortened to <code>rtg</code>). The argument to the command is the URL of the Global Discovery Server (GDS). The <code>-eu</code> option (shortened form of <code>--EndpointUser</code>) specifies the user name and password for user authentication to the GDS, separated by a colon (':'). If your GDS does not require user authentication (which would be quite insecure), you can leave this option out. Other user authentication options are also available (see the help for the command). The command argument and option is repeated in many commands further below, and they have the same meaning.<br/>When the operation is successful, the GDS assigns an application ID to the client application, and the OpcCmd utility displays this application ID to you. The application ID is an OPC UA node ID for a node that represents the application inside the GDS for further operations.<br/><br/>
# In order to verify the registrations that exist inside the GDS for the client application, enter {{Style=keyboard|findGdsRegistrations opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>findGdsRegistrations</code> can be shortened to <code>fgr</code>). The command displays a list of registrations for this client application. There is normally just one registration, but in some cases there may be more. The list includes the application ID, application type (usually Client), application name, and the discovery URI (with servers).<br/><br/>
# You can obtain a new client certificate from the GDS by entering {{Style=keyboard|obtainNewCertificate opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>obtainNewCertificate</code> can be shortened to <code>onc</code>). When the command is successful, the certificate from the GDS (which serves as certification authority) is stored into the certificate store on the client side, and will be used by this client in its subsequent operations (be aware that this has the potential of affecting whether connection can be made to various servers by the client or not; further down in this tutorial, you will find how to revert this action). In the process, trusted issuer certificates at the client side are also updated.<br/>This is a multi-step operation, and it may take a considerable time to complete. The program displays progress messages as it performs the various steps. The client registration in the GDS is updated first. In some cases, a manual confirmation might be needed on the GDS side, before the GDS issues a certificate to the client; in such case, the command will not complete until somebody operating the GDS approves the certificate request. After the command is successfully completed, it displays the (main parameters of) the new client certificate.<br/><br/>
# The GDS contents evolves in time, and the set of trusted applications may change. For example, some certificates might be revoked, and this information needs to be updated in the client application. In order to do so, enter {{Style=keyboard|refreshTrustLists opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>refreshTrustLists</code> can be shortened to <code>rtl</code>). If the command is successful, it displays the the types of trust lists that have been updated, and uses the updated trust lists subsequently.<br/><br/>
# To remove the application registration from the GDS, enter {{Style=keyboard|unregisterFromGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>unregisterFromGds</code> can be shortened to <code>ufg</code>). If the operation is successful, the previously assigned application ID becomes invalid.<br/><br/>
# You can check the parameters of the currently used client instance certificate at any time by entering {{Style=keyboard|findOwnCertificate}}, or shortened: {{Style=keyboard|foc}}.<br/><br/>
# If you want to force the application to generate a new self-signed client certificate, you can do so by entering {{Style=keyboard|removeOwnCertificates}}, or shortened: {{Style=keyboard|roc}}. This might be useful e.g. for repeated testing against a GDS, if you have already received a client certificate from GDS (signed by a certificate authority), and want to revert to the initial state. At the next OPC UA operation, the application will generate a new self-signed certificate for itself, and use it for subsequent operations. The command will ask you for confirmation; press {{Style=keyboard|Y}} for "Yes".

== Explanation of service statefulness ==
The OPC UA client application service is stateful: It remembers how it has registered the client into the GDS server(s), and the application IDs assigned, etc. The actual actions made to the GDS depend on the current state. For example, the tutorial instructs you to perform the <code>registerToGds</code> before <code>obtainNewCertificate</code>, but in fact, this is not necessary. The <code>obtainNewCertificate</code> can be issued right away, and if the client application service detects that the client has not yet been registered with the GDS, it will register itself first. Also, commands like <code>registerToGds</code>, <code>updateGdsRegistration </code> and <code>unregisterFromGds</code> are designed in such a way that they do not require you to know whether the client is currently registered with the GDS or not. You will '''not''' get an error if the current state is not as it should be: The important thing is the desired outcome of the command, and the command will attempt to get you that desired outcome. For example, <code>updateGdsRegistration</code> will actually create a new registration if one does not exist yet. <code>unregisterFromGds</code>, if succeeded, guarantees that the client is unregistered - and that is true even if it has not been registered before. You need to keep statefulness of the service in mind if you use it to test the GDS, because the same command does not always result in the same actions against the GDS.

Part of the application state is also the mapping between the requested and actual certificate subject names, because the Certificate Manager may modify the requested subject name when issuing a new certificate.

The application state is persisted on the disk. This means that when the application is terminated and then started again, the state information from the previous run will be reused. The state is persisted in the '''UAApplication.ini''' file.

== Other commands ==
Other commands at the {{Style=label|uaApplication>}} prompt, not used in this tutorial, include:
* <code>applicationIdDictionary?</code>
* <code>assureOwnCertificate</code>
* <code>createOwnCertificate</code>
* <code>exportRegisteredApplication</code>
* <code>exportSecuredApplication</code>
* <code>getApplicationElement</code>
* <code>getCertificateSubjectName</code>
* <code>getCertificateSubjectNameDictionary</code>
* <code>updateGdsRegistration</code>
* <code>validateOwnCertificate</code>

== Peeking into the list of applications registered to a GDS ==
Somewhat related to the topic of the tutorial, if you are interested not just in the registration of a single application, but want to view other applications that that has registered to the GDS, enter the {{Style=keyboard|exit}} command to get back to the {{Style=label|OpcCmd>}} prompt, and then enter

{{Style=keyboard|uaClient discover globalApplications opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer}}

This will show a table of all applications registered to the specified GDS, each entry together with its application type, application name, discovery URI, etc.
<br/>
<br/>