Command line syntax improvements #80

LukeLR commented 2025年10月20日 15:15:57 +02:00

Hi everyone,

coming from the old OpenVPN 2 client, the openvpn3 command line syntax feels a little complicated for me as an outsider. I know that openvpn3 is more modern and e.g. managing multiple connections in background imposes some requirements on the command line interface, but I still have a feeling the syntax could be less complicated. I'd like to propose some ideas for a simplified command line syntax.

For example, connections are started using session-start, but disconnecting requires session-manage --disconnect. While it makes sense from a developer perspective (a session can only be managed if it was started first), it is hard to understand from a users perspective (Why is there a separate command for starting sessions, but disconnecting sessions is only a subcommand to session-manage?) From a consistency point of view, it would make more sense to either move session starting to session-manage --start, or introduce a session-disconnect command which might just be an alias to session-manage --disconnect.

Furthermore, openvpn3 session-manage --disconnect --config config-name is a quite lengthy command to type, so a session-disconnect command would help here as well. One could even think about ditching the session- prefix, commands like openvpn3 connect, openvpn3 disconnect etc. would still be unambiguous. Or removing the need to specify --config config-name, this would be a good use case for a positional argument, that is always required unless --path is given or something. The config file argument could even be omitted if only one session is established.

If these improvements would be applied, we could reduce a lengthy command to disconnect a session like

openvpn3 session-manage --disconnect --config config-name

to a much shorter version like

openvpn3 disconnect config-name

or even

openvpn3 disconnect

which would not only be much faster to type, it would also be much easier to explain to our less tech-savy Linux users that are just researchers or students and not developers or system administrators.

It might be that I'm missing something and using openvpn3 in an overly-complicated manner, or maybe I'm the only one who was a bit intimidated by the command line syntax on first use, or maybe there are technical reasons why a simpler command line syntax is not possible, that I simply don't know as an outsider. But at least I wanted to start a discussion on that topic ;)

Hi everyone, coming from the old OpenVPN 2 client, the openvpn3 command line syntax feels a little complicated for me as an outsider. I know that openvpn3 is more modern and e.g. managing multiple connections in background imposes some requirements on the command line interface, but I still have a feeling the syntax could be less complicated. I'd like to propose some ideas for a simplified command line syntax. For example, connections are started using `session-start`, but disconnecting requires `session-manage --disconnect`. While it makes sense from a developer perspective (a session can only be managed if it was started first), it is hard to understand from a users perspective (Why is there a separate command for starting sessions, but disconnecting sessions is only a subcommand to `session-manage`?) From a consistency point of view, it would make more sense to either move session starting to `session-manage --start`, or introduce a `session-disconnect` command which might just be an alias to `session-manage --disconnect`. Furthermore, `openvpn3 session-manage --disconnect --config config-name` is a quite lengthy command to type, so a `session-disconnect` command would help here as well. One could even think about ditching the `session-` prefix, commands like `openvpn3 connect`, `openvpn3 disconnect` etc. would still be unambiguous. Or removing the need to specify `--config config-name`, this would be a good use case for a positional argument, that is always required unless `--path` is given or something. The config file argument could even be omitted if only one session is established. If these improvements would be applied, we could reduce a lengthy command to disconnect a session like ``` openvpn3 session-manage --disconnect --config config-name ``` to a much shorter version like ``` openvpn3 disconnect config-name ``` or even ``` openvpn3 disconnect ``` which would not only be much faster to type, it would also be much easier to explain to our less tech-savy Linux users that are just researchers or students and not developers or system administrators. It might be that I'm missing something and using openvpn3 in an overly-complicated manner, or maybe I'm the only one who was a bit intimidated by the command line syntax on first use, or maybe there are technical reasons why a simpler command line syntax is not possible, that I simply don't know as an outsider. But at least I wanted to start a discussion on that topic ;)

dazo commented 2025年10月21日 09:52:42 +02:00

Thanks a lot for your input, @LukeLR!

Yeah, I agree to a lot of your arguments. For some time I've been pondering of adding session-manage --start, and keep session-start as an alias to that.

About the direct connect and disconnect, while I agree to the "typing" aspect - but it actually looses the "command context" aspect. As you say, the OpenVPN 3 Linux project is very different from OpenVPN 2.x. The main difference is that it there is a complete management stack in OpenVPN 3.

The "good old" /usr/sbin/openvpn binary is kind of the equivalent of just the openvpn3-service-client and openvpn3-service-netcfg services. And the end users does not have any direct access to these two binaries; they need to go via the openvpn3-service-sessionmgr - which can reached via the openvpn3 session* commands. Management of the configuration profiles are done via openvpn3 config* commands.

These openvpn3-service-* processes are part of how we have managed to make end users without any system privileges to manage their own VPN configs and sessions. This privilege separation is provided via the D-Bus framework.

One thing on the "typing verbosity" - I don't know which shell you use, but there should be fairly good shell completion support for both bash (and zsh, but I have little experience on the setup here). You might need to install the bash-completion package to make it work. I've also been playing a bit with completion support for fish as well, but that's not materialized enough to be part of a release. But I can share my PoC if anyone is interested in contributing further.

And there are also short arguments to most of the commands.

 $ openvpn3 session-start -c CONFIG_NAME
 $ openvpn3 session-manage -c CONFIG_NAME -D # --disconnect

I took quit a lot of "inspiration" from the nmcli command, which also groups commands. And maybe it's time to take even more ideas from it. Like:

 # Start session
 $ ovpn3 session start <CONFIG_NAME | CONFIG_PATH>
 $ ovpn3 s s <CONFIG_NAME | CONFIG_PATH>
 # Disconnect session
 $ ovpn3 session disconnect <CONFIG_NAME | CONFIG_PATH>
 $ ovpn3 s d <CONFIG_NAME | CONFIG_PATH>
 # Session stats
 $ ovpn3 session stats <CONFIG_NAME | SESSION_PATH>
 $ ovpn3 s st <CONFIG_NAME | SESSION_PATH>
 $ ovpn3 session stats interface <TUN/DCO_INTERFACE>
 $ ovpn3 s st i <TUN/DCO_INTERFACE>

and so on .... and of course, with shell completion support.

I'm thinking this as a new binary, to not make the code for the openvpn3 command more complicated. But it should be possible to re-use most of the code which "performs" these operations with a little adaptation.

As a final note, all what the openvpn3 command (and to a large degree, openvpn3-admin) does - is just to do D-Bus calls to the openvpn3-service-* processes. Most of the "heavy work" happens inside these services. The openvpn3-indicator project is a brilliant example of this. Another example is the /usr/bin/openvpn2 (poor name, tbh) - which mimics the client mode of the "good old" /usr/sbin/openvpn. Both openvpn3-indicator and the openvpn2 command are written in Python.

Thanks a lot for your input, @LukeLR! Yeah, I agree to a lot of your arguments. For some time I've been pondering of adding `session-manage --start`, and keep `session-start` as an alias to that. About the direct `connect` and `disconnect`, while I agree to the "typing" aspect - but it actually looses the "command context" aspect. As you say, the OpenVPN 3 Linux project is very different from OpenVPN 2.x. The main difference is that it there is a complete management stack in OpenVPN 3. The "good old" `/usr/sbin/openvpn` binary is kind of the equivalent of just the `openvpn3-service-client` and `openvpn3-service-netcfg` services. And the end users does not have any direct access to these two binaries; they need to go via the `openvpn3-service-sessionmgr` - which can reached via the `openvpn3 session*` commands. Management of the configuration profiles are done via `openvpn3 config*` commands. These `openvpn3-service-*` processes are part of how we have managed to make end users without any system privileges to manage their own VPN configs and sessions. This privilege separation is provided via the D-Bus framework. One thing on the "typing verbosity" - I don't know which shell you use, but there should be fairly good shell completion support for both `bash` (and `zsh`, but I have little experience on the setup here). You might need to install the `bash-completion` package to make it work. I've also been playing a bit with completion support for `fish` as well, but that's not materialized enough to be part of a release. But I can share my PoC if anyone is interested in contributing further. And there are also short arguments to most of the commands. $ openvpn3 session-start -c CONFIG_NAME $ openvpn3 session-manage -c CONFIG_NAME -D # --disconnect I took quit a lot of "inspiration" from the `nmcli` command, which also groups commands. And maybe it's time to take even more ideas from it. Like: # Start session $ ovpn3 session start <CONFIG_NAME | CONFIG_PATH> $ ovpn3 s s <CONFIG_NAME | CONFIG_PATH> # Disconnect session $ ovpn3 session disconnect <CONFIG_NAME | CONFIG_PATH> $ ovpn3 s d <CONFIG_NAME | CONFIG_PATH> # Session stats $ ovpn3 session stats <CONFIG_NAME | SESSION_PATH> $ ovpn3 s st <CONFIG_NAME | SESSION_PATH> $ ovpn3 session stats interface <TUN/DCO_INTERFACE> $ ovpn3 s st i <TUN/DCO_INTERFACE> and so on .... and of course, with shell completion support. I'm thinking this as a new binary, to not make the code for the `openvpn3` command more complicated. But it should be possible to re-use most of the code which "performs" these operations with a little adaptation. As a final note, all what the `openvpn3` command (and to a large degree, `openvpn3-admin`) does - is just to do D-Bus calls to the `openvpn3-service-*` processes. Most of the "heavy work" happens inside these services. The [openvpn3-indicator](https://github.com/OpenVPN/openvpn3-indicator/) project is a brilliant example of this. Another example is the `/usr/bin/openvpn2` (poor name, tbh) - which mimics the client mode of the "good old" `/usr/sbin/openvpn`. Both `openvpn3-indicator` and the `openvpn2` command are written in Python.

LukeLR commented 2025年11月04日 17:16:09 +01:00

Thank your for looking into my issue! You're right, there's short versions of the commands, and bash completion is also helpful. I am mostly searching for the appropriate commands in my history using Ctrl+R as an experienced Linux user, without typing the commands at all. But I'm asking because I'm supporting less experienced Linux users at my university, e.g. in research. And for them, the complicated command line syntax is difficult to understand. Of course, I'll also point them to bash completion and short versions of the arguments, but in many cases, good documentation and bash completion cannot replace memorizing and understanding the command line syntax.

Therefore, it would still be helpful if the syntax would be straightforward and easy to memorize in the first place. I like your idea of a short syntax similar to the nmcli command. I think, a syntax like this would be a good fit for the openvpn3 utility as well, even if provided via a separate executable.

Thank your for looking into my issue! You're right, there's short versions of the commands, and bash completion is also helpful. I am mostly searching for the appropriate commands in my history using Ctrl+R as an experienced Linux user, without typing the commands at all. But I'm asking because I'm supporting less experienced Linux users at my university, e.g. in research. And for them, the complicated command line syntax is difficult to understand. Of course, I'll also point them to bash completion and short versions of the arguments, but in many cases, good documentation and bash completion cannot replace memorizing and understanding the command line syntax. Therefore, it would still be helpful if the syntax would be straightforward and easy to memorize in the first place. I like your idea of a short syntax similar to the `nmcli` command. I think, a syntax like this would be a good fit for the `openvpn3` utility as well, even if provided via a separate executable.