diff --git a/build/templates/conf.py.mako b/build/templates/conf.py.mako index 35d1aa445..6303802d3 100644 --- a/build/templates/conf.py.mako +++ b/build/templates/conf.py.mako @@ -204,4 +204,6 @@ intersphinx_mapping = { % for module in sorted(external_modules): '${module}': ('https://${module}.readthedocs.io/en/latest/', None), % endfor + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/build/templates/grpc_session_options.rst.mako b/build/templates/grpc_session_options.rst.mako index 05cb46f5b..0da15f31e 100644 --- a/build/templates/grpc_session_options.rst.mako +++ b/build/templates/grpc_session_options.rst.mako @@ -14,6 +14,54 @@ Support for using ${driver_name} over gRPC +Creating a gRPC channel +----------------------- + +Using ${driver_name} over gRPC requires the ``grpc`` extra:: + + $ python -m pip install ${module_name}[grpc] + +Every ${driver_name} gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`${module_name}.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +${driver_name} runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import ${module_name} + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = ${module_name}.GrpcSessionOptions(channel, '') + with ${module_name}.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -62,17 +110,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -81,18 +129,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`${module_name}.SessionInitializationBehavior` diff --git a/docs/nidcpower/conf.py b/docs/nidcpower/conf.py index c8bd63d6f..e8eafe2da 100644 --- a/docs/nidcpower/conf.py +++ b/docs/nidcpower/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nidcpower/grpc_session_options.rst b/docs/nidcpower/grpc_session_options.rst index 00265cdfd..5c67fb9a5 100644 --- a/docs/nidcpower/grpc_session_options.rst +++ b/docs/nidcpower/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-DCPower over gRPC +Creating a gRPC channel +----------------------- + +Using NI-DCPower over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidcpower[grpc] + +Every NI-DCPower gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidcpower.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-DCPower runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidcpower + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidcpower.GrpcSessionOptions(channel, '') + with nidcpower.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidcpower.SessionInitializationBehavior` diff --git a/docs/nidigital/conf.py b/docs/nidigital/conf.py index 65562b104..67fade284 100644 --- a/docs/nidigital/conf.py +++ b/docs/nidigital/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nidigital/grpc_session_options.rst b/docs/nidigital/grpc_session_options.rst index f868c64d5..41e1e3de5 100644 --- a/docs/nidigital/grpc_session_options.rst +++ b/docs/nidigital/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-Digital Pattern Driver over gRPC +Creating a gRPC channel +----------------------- + +Using NI-Digital Pattern Driver over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidigital[grpc] + +Every NI-Digital Pattern Driver gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidigital.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-Digital Pattern Driver runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidigital + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidigital.GrpcSessionOptions(channel, '') + with nidigital.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidigital.SessionInitializationBehavior` diff --git a/docs/nidmm/conf.py b/docs/nidmm/conf.py index 9fc90f043..28f34b549 100644 --- a/docs/nidmm/conf.py +++ b/docs/nidmm/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nidmm/grpc_session_options.rst b/docs/nidmm/grpc_session_options.rst index 9eaf91c83..97a6f481b 100644 --- a/docs/nidmm/grpc_session_options.rst +++ b/docs/nidmm/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-DMM over gRPC +Creating a gRPC channel +----------------------- + +Using NI-DMM over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nidmm[grpc] + +Every NI-DMM gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nidmm.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-DMM runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nidmm + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nidmm.GrpcSessionOptions(channel, '') + with nidmm.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nidmm.SessionInitializationBehavior` diff --git a/docs/nifgen/conf.py b/docs/nifgen/conf.py index 63eef5147..64f022df0 100644 --- a/docs/nifgen/conf.py +++ b/docs/nifgen/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nifgen/grpc_session_options.rst b/docs/nifgen/grpc_session_options.rst index 2752e1d18..976e7dd48 100644 --- a/docs/nifgen/grpc_session_options.rst +++ b/docs/nifgen/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-FGEN over gRPC +Creating a gRPC channel +----------------------- + +Using NI-FGEN over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nifgen[grpc] + +Every NI-FGEN gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nifgen.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-FGEN runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nifgen + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nifgen.GrpcSessionOptions(channel, '') + with nifgen.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nifgen.SessionInitializationBehavior` diff --git a/docs/nimodinst/conf.py b/docs/nimodinst/conf.py index a6644f21d..8fed7fdc7 100644 --- a/docs/nimodinst/conf.py +++ b/docs/nimodinst/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nirfsa/conf.py b/docs/nirfsa/conf.py index 60ff10c23..c41e58f88 100644 --- a/docs/nirfsa/conf.py +++ b/docs/nirfsa/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nirfsa/grpc_session_options.rst b/docs/nirfsa/grpc_session_options.rst index 0c939dec8..8176959ea 100644 --- a/docs/nirfsa/grpc_session_options.rst +++ b/docs/nirfsa/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-RFSA over gRPC +Creating a gRPC channel +----------------------- + +Using NI-RFSA over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nirfsa[grpc] + +Every NI-RFSA gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nirfsa.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-RFSA runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nirfsa + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nirfsa.GrpcSessionOptions(channel, '') + with nirfsa.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nirfsa.SessionInitializationBehavior` diff --git a/docs/nirfsg/conf.py b/docs/nirfsg/conf.py index 02551f0ba..110386ef8 100644 --- a/docs/nirfsg/conf.py +++ b/docs/nirfsg/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/nirfsg/grpc_session_options.rst b/docs/nirfsg/grpc_session_options.rst index 73d27acff..87595dc7f 100644 --- a/docs/nirfsg/grpc_session_options.rst +++ b/docs/nirfsg/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-RFSG over gRPC +Creating a gRPC channel +----------------------- + +Using NI-RFSG over gRPC requires the ``grpc`` extra:: + + $ python -m pip install nirfsg[grpc] + +Every NI-RFSG gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`nirfsg.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-RFSG runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import nirfsg + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = nirfsg.GrpcSessionOptions(channel, '') + with nirfsg.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`nirfsg.SessionInitializationBehavior` diff --git a/docs/niscope/conf.py b/docs/niscope/conf.py index 602415bf8..6d27c59cd 100644 --- a/docs/niscope/conf.py +++ b/docs/niscope/conf.py @@ -195,4 +195,6 @@ def setup(app): 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/niscope/grpc_session_options.rst b/docs/niscope/grpc_session_options.rst index a944c230a..1d3ff6459 100644 --- a/docs/niscope/grpc_session_options.rst +++ b/docs/niscope/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-SCOPE over gRPC +Creating a gRPC channel +----------------------- + +Using NI-SCOPE over gRPC requires the ``grpc`` extra:: + + $ python -m pip install niscope[grpc] + +Every NI-SCOPE gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`niscope.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-SCOPE runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import niscope + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = niscope.GrpcSessionOptions(channel, '') + with niscope.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`niscope.SessionInitializationBehavior` diff --git a/docs/nise/conf.py b/docs/nise/conf.py index dc149a511..8421ee750 100644 --- a/docs/nise/conf.py +++ b/docs/nise/conf.py @@ -195,4 +195,6 @@ def setup(app): 'niscope': ('https://niscope.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/niswitch/conf.py b/docs/niswitch/conf.py index e4b48cf57..af61a15ba 100644 --- a/docs/niswitch/conf.py +++ b/docs/niswitch/conf.py @@ -195,4 +195,6 @@ def setup(app): 'niscope': ('https://niscope.readthedocs.io/en/latest/', None), 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'nitclk': ('https://nitclk.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), } diff --git a/docs/niswitch/grpc_session_options.rst b/docs/niswitch/grpc_session_options.rst index e0271e078..474d9705a 100644 --- a/docs/niswitch/grpc_session_options.rst +++ b/docs/niswitch/grpc_session_options.rst @@ -7,6 +7,54 @@ Support for using NI-SWITCH over gRPC +Creating a gRPC channel +----------------------- + +Using NI-SWITCH over gRPC requires the ``grpc`` extra:: + + $ python -m pip install niswitch[grpc] + +Every NI-SWITCH gRPC session is created from a ``grpc.Channel`` that you build and pass to +:py:class:`niswitch.GrpcSessionOptions`. You own the channel, not the session, so you must +close it after the last session using it is closed. + +The recommended way to create a gRPC channel to a remote system running NI gRPC Device Server is +:py:func:`nitlsconfig.create_grpc_device_channel() ` +from the `nitlsconfig `_ package, which the +``grpc`` extra installs for you. It reads the nitlsconfig client configuration installed with the +NI-SWITCH runtime and by default will attempt to build an encrypted gRPC channel using mTLS. + +Before ``create_grpc_device_channel`` can succeed, you must use NI Hardware Manager to perform a +certificate exchange with the remote system. +See `Managing mTLS `_ for +additional information. + +For example:: + + import niswitch + import nitlsconfig + + with nitlsconfig.create_grpc_device_channel('remote_grpc_device', 31763) as channel: + options = niswitch.GrpcSessionOptions(channel, '') + with niswitch.Session('dev1', grpc_options=options) as session: + # Calls to session over the encrypted channel + +.. note:: From NI Hardware Manager, you can disable TLS to make ``create_grpc_device_channel`` + produce an insecure channel. + +.. note:: ``create_grpc_device_channel`` also accepts an ``options`` parameter for gRPC channel + arguments such as ``grpc.ssl_target_name_override``, and a ``retry_policy`` parameter. Channel + arguments cannot be changed after the channel is built, so they must be supplied here. + +.. note:: NI gRPC Device Server must be configured to accept remote connections and to take its + TLS settings from nitlsconfig. See + `Bind Address Support `_ and + `NI TLS Config Integration `_ for details. + +You can also build the gRPC channel yourself with ``grpc.insecure_channel`` or ``grpc.secure_channel`` +if you need full control over how credentials are supplied. + + SessionInitializationBehavior ----------------------------- @@ -55,17 +103,17 @@ GrpcSessionOptions :param grpc_channel: - + Specifies the channel to the NI gRPC Device Server. - + :type grpc_channel: grpc.Channel :param session_name: - + User-specified name that identifies the driver session on the NI gRPC Device Server. @@ -74,18 +122,18 @@ GrpcSessionOptions You can use an empty string if you want to always initialize a new session on the server. To attach to an existing session, you must specify the session name it was initialized with. - + :type session_name: str :param initialization_behavior: - + Specifies whether it is acceptable to initialize a new session or attach to an existing one, or if only one of the behaviors is desired. The driver session exists on the NI gRPC Device Server. - + :type initialization_behavior: :py:data:`niswitch.SessionInitializationBehavior` diff --git a/docs/nitclk/conf.py b/docs/nitclk/conf.py index 5de00c1b2..80ad91832 100644 --- a/docs/nitclk/conf.py +++ b/docs/nitclk/conf.py @@ -195,4 +195,6 @@ def setup(app): 'niscope': ('https://niscope.readthedocs.io/en/latest/', None), 'nise': ('https://nise.readthedocs.io/en/latest/', None), 'niswitch': ('https://niswitch.readthedocs.io/en/latest/', None), + # Read the Docs project slug differs from the module name. + 'nitlsconfig': ('https://nitlsconfig-python.readthedocs.io/en/latest/', None), }