OPC UA Client Application Operations in OpcCmd: Difference between revisions

From OPC Labs Knowledge Base
No edit summary
No edit summary
Line 7: Line 7:
# 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).
# 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).
# 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 is 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. 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.
# 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 is 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. 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.
# ?
# 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.
# {{Style=keyboard|refreshTrustLists opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>refreshTrustLists</code> can be shortened to <code>rtl</code>).
# {{Style=keyboard|unregisterFromGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>unregisterFromGds</code> can be shortened to <code>ufg</code>).
# {{Style=keyboard|unregisterFromGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo}} (<code>unregisterFromGds</code> can be shortened to <code>ufg</code>).
# You can check the parameters of the currently used client instance certificate at any time by entering {{Style=keyboard|getInstanceCertificate}}, or shortened: {{Style=keyboard|gic}}.
# You can check the parameters of the currently used client instance certificate at any time by entering {{Style=keyboard|getInstanceCertificate}}, or shortened: {{Style=keyboard|gic}}.
Line 20: Line 19:
* <code>getCertificateSubjectName</code>
* <code>getCertificateSubjectName</code>
* <code>updateGdsRegistration</code>
* <code>updateGdsRegistration</code>
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 registerToGds before obtainNewCertificate, but in fact, this is not necessary. The obtainNewCertificat 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, the commands registerToGds, updateGdsRegistration and unregisterFromGds 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. For example, updateGdsRegistration will actually create a new registration if one does not exist yet. unregisterFromGds, if succeeded, guarantees that the client is unregistered - and that is true even it it has not been registered before.
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, the commands <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. 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 it 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.

Revision as of 11:35, 15 January 2021

Tutorial

If you execute the commands listed in the tutorial below, you will get an overview of available client application operations.

  1. At the OpcCmd> prompt, enter uaClient getService uaClientApplication, or shortened: uac gs uaca.
    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 creates its self-signed client certificate.
    All following commands are entered at the uaClientApplication> prompt. You can enter -?, -h or --help (possibly preceded by the command name) at any time to obtain help for this prompt (or its commands).
  2. In order to create application registration ibn the GDS, enter registerToGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo (registerToGds can be shortened to rtg). The argument to the command is the URL of the Global Discovery Server (GDS). The -eu option (shortened form of --EndpointUser) specifies the user name and password for user authentication to the GDS. The command argument and option is repeated in many commands further below, and they have the same meaning. 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 an OPC UA node ID for a node that represents the application inside the GDS.
  3. In order to verify the registrations that exist inside the GDS for the client application, enter findGdsRegistrations opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo (findGdsRegistrations can be shortened to fgr). 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).
  4. You can obtain a new client certificate from the GDS by entering obtainNewCertificate opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo (obtainNewCertificate can be shortened to onc). 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 is 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.
    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. 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.
  5. 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 refreshTrustLists opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo (refreshTrustLists can be shortened to rtl). If the command is successful, it displays the the types of trust lists that have been updated, and uses the updated trust lists subsequently.
  6. unregisterFromGds opc.tcp://opcua.demo-this.com:58810/GlobalDiscoveryServer -eu appadmin:demo (unregisterFromGds can be shortened to ufg).
  7. You can check the parameters of the currently used client instance certificate at any time by entering getInstanceCertificate, or shortened: gic.
  8. If you want to force the application to generate a new self-signed client certificate, you can do so by entering removeInstanceCertificate, or shortened: ric. 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.

Other commands at the uaClientApplication> prompt, not used in this tutorial, include:

  • applicationIdDictionary?
  • exportRegisteredApplication
  • exportSecuredApplication
  • getApplicationElement
  • getCertificateSubjectName
  • updateGdsRegistration

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 registerToGds before obtainNewCertificate, but in fact, this is not necessary. The obtainNewCertificate 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, the commands registerToGds, updateGdsRegistration and unregisterFromGds 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. For example, updateGdsRegistration will actually create a new registration if one does not exist yet. unregisterFromGds, if succeeded, guarantees that the client is unregistered - and that is true even it 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.