Frequently Asked Questions¶
General gRPC questions¶
Can I use gRPC with languages other than C++ and Python?¶
Yes! gRPC supports many programming languages, including C++, Python, Go and C#. The gRPC tools can generate client and server code for these languages.
See: https://grpc.io/docs/languages/
How do I create a gRPC client?¶
To create a gRPC client, you typically need to generate client code using the gRPC tools from your service definition file (.proto). Then, you can use the generated client classes to make RPC calls to the server.
Where are the protobufs located?¶
The proto files for each service in EosSdkRpc are located either on this github repository, or in the /usr/share/EosSdkRpc/proto directory on an Arista EOS device.
How to generate source files for a given language from the proto files?¶
C++: see the simple c++ client
Python: If you haven't already, you need to install the Protocol Buffers compiler (protoc). You can download precompiled binaries from the official repository: https://github.com/protocolbuffers/protobuf/releases
You'll also need the grpcio-tools package to generate gRPC code for Python. You can install it using pip:
Use the protoc compiler and the python_out option to generate Python code from your .proto file:
Replace /path/to/protobufs with the actual path to the directory containing your .proto file, and replace /path/to/output_dir with the directory where you want the Python code to be generated.How many clients are able to connect to a single transport?¶
There is no maximum number of clients for a gRPC server; it's a dynamic and context-dependent parameter that should be determined on a case by case basis due to hardware and performance constraints.
However, as with most gRPC servers EosSdkRpc allows a max of 100 concurrent streams by default. A gRPC channel uses one HTTP/2 connection, and all concurrent calls are multiplexed on that single connection. If the amount of active calls hits the connection stream limit, any additional calls made will be added to a queue in the client. These calls in the queue must wait for other active calls to complete before they are sent.
See: https://grpc.io/docs/guides/performance/
What is the maximum message size?¶
The max message size in gRPC is limited to 4MB by default. This can be increased by setting the following client channel options: - grpc.max_send_message_length - Grpc.max_receive_message_length
This should only be required in very specific cases. For example, making a show command request with the EapiService that returns a large amount of content.
How can I handle timeouts and deadlines in gRPC clients?¶
You can set timeouts and deadlines when making RPC calls using gRPC. This helps ensure that calls do not hang indefinitely and fail gracefully when expected responses are not received within the specified time.
Python Example:
Python example
Use the optional timeout parameter, which sets duration of time in seconds to allow for the RPC.
How do I handle errors in gRPC clients?¶
gRPC uses status codes to indicate the outcome of an RPC call. The returned grpc::Status object should be checked to determine the status of the call and handle errors accordingly.
Info
Sample mapping of EOS SDK errors to gRPC errors can be found in our HOWTO guide
Common Errors:¶
| gRPC Status | description |
|---|---|
| GRPC_STATUS_CANCELLED | The request was cancelled |
| GRPC_STATUS_DEADLINE_EXCEEDED | The request deadline expired before the server returned a response |
| GRPC_STATUS_UNIMPLEMENTED | The RPC has not been implemented on the server side. This could be because the service has not been enabled via the EosSdkRpc transport service configuration command: service <list of services to enable> | all |
| GRPC_STATUS_UNAVAILABLE | This status code usually indicates the client is unable to form a successful connection to the server. This can be caused by many issues depending on the language used by the client. Common causes are the gRPC server not running, ACL rules blocking the IP/port, certificate issues, attempting to connect to a different server. |
| GRPC_STATUS_UNKNOWN | Server may have thrown an exception |
Info
See: official gRPC website for further information.
Other:¶
RPC inactive/failed to connect to address¶
Please ensure the Arista device has the correct access control in place to permit traffic on the port used to configure the given EosSdkRpc transport. The default EosSdkRpc port is blocked by default and must be explicitly enabled for remote clients connecting over an interface.
See the exposing the RPC port guide.
No match found for server name: ¶
If an SSL profile is in use and there is a mismatch between the common name (or SAN) of the certificate and the device the following trace will appear in the logs (/var/log/agents/EosSdkRpcAgent-
E0223 09:47:05.375500672 30883 ssl_transport_security.cc:1839] No match found for server name: <dns name>
Ensure the server certificate has the dns name or IP address, which is used by the client to connect to the server present in the CN or SAN field.
Peer did not return a certificate.¶
If the transport is enabled with mTLS config ( trust certificate <certificate> configuration present in the configured SSL profile ) and the client does not provide a valid certificate, a similar trace to the following will appear in the logs:
E0223 09:53:34.288937269 32483 ssl_transport_security.cc:1469] Handshake failed with fatal error SSL_ERROR_SSL: error:140890C7:SSL routines:ssl3_get_client_certificate:peer did not return a certificate.
Note
A client certificate may also be validated against a trusted certificate manually using the following openssl command:
RSA_padding_check_PKCS1_type_1:block type is not 01¶
If the certificate presented to the server by the client is not signed by a trusted CA, a trace similar to the following may appear in the logs:
E0223 09:59:07.960911143 32483 ssl_transport_security.cc:1469] Handshake failed with fatal error SSL_ERROR_SSL: error:0407006A:rsa routines:RSA_padding_check_PKCS1_type_1:block type is not 01.
Questions specific to EosSdkRpc¶
How can I secure gRPC communication?¶
gRPC supports various security mechanisms, including Transport Layer Security (TLS) for securing communication between clients and servers. You can configure security options when setting up the server and client by first configuring an SSL profile within EOS. Optional, AAA username and password authentication is also supported as an additional layer ontop of TLS.
See the security configuration guide for more information.
Troubleshooting EosSdkRpc¶
Where are EosSdkRpc logs located?¶
The logs for EosSdkRpc transports are located in /var/log/agents directory, the naming format for each transport will be
EosSdkRpcAgent-<transport name>-<process id>
e.g EosSdkRpcAgent-foo-12345
How to enable more verbose EosSdkRpc gRPC logging:¶
All C core library based gRPC implementations have built in support for both of the GRPC_VERBOSITY and GRPC_TRACE environment variables. These can be used to enable more verbose logging from within gRPC for both the EosSdkRpc transport and the client.
Other gRPC environment variables may be found at the official gRPC github
Server-side¶
Set the environment variable for the transport named foo ( agent name: EosSdkRpcAgent-foo ):
The agent must be restarted for the environment variable to take effect:
hostname(config)#
hostname(config)#man api eos-sdk-rpc
hostname(config-mgmt-api-eos-sdk-rpc)#transport grpc foo
hostname(config-eos-sdk-rpc-transport-default)#disabled
hostname(config-eos-sdk-rpc-transport-default)#no disabled
This is an EosSdk application
Full agent name is 'EosSdkRpcAgent-foo
More verbose logging should now be present in: /var/log/agents/EosSdkRpcAgent-foo-<pid>
Client-side¶
Examples:
Python:
GRPC_VERBOSITY=debug python Client.py
Dotnet:
GRPC_VERBOSITY=debug dotnet run
How to verify the EosSdkRpc process is running?¶
bash and pgrep
hostname(config)#bash pgrep EosSdkRpc | xargs ps PID TTY STAT TIME COMMAND 26963 ? Sl 0:07 EosSdkRpc-RPC
or
Info
sh daemon Agent: RPC (running with PID 26963) Uptime: 0:00:39 (Start time: Thu Feb 23 09:25:10 2023) No configuration options stored.
No status data stored.
How to verify the EosSdkRpc transport is actively listening on the configured addresses?¶
using netstat and grep:
hostname(config)#bash sudo netstat -ptnl | grep 9543
tcp6 0 0 :::9543 :::* LISTEN 26963/EosSdkRpc-RPC
-x for unix socket
-t for tcp
How to verify the port is being forwarded in the configured ACLs?¶
Use the show run | sec <port> command to easily parse the running config for any custom access-list.
Verify the correct access-list is in use: