Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

PUSH_UPDATE: improve feature description #7

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

PUSH_UPDATE: improve feature description #7

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 23 additions & 9 deletions openvpn-wire-protocol.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1817,30 +1817,44 @@ datakeys = TLS_PRF(key_seed, key_seed)
</section>
<section anchor="pushupdate" title="PUSH_UPDATE">
<t>
Format: <sourcecode>PUSH_UPDATE [comma separated options]</sourcecode>
Format: <sourcecode>PUSH_UPDATE [comma-separated options]</sourcecode>
</t>
<t>
This message includes dynamic configuration options that can be pushed from the server to the client without reconnecting.
These options augment existing options. Options with the same name are replaced. To remove an option, it should be prefixed
with <tt>-</tt>. For example, the following code replaces all routes (if there were any) with the provided one and removes the <tt>dns</tt> option:
These options augment existing ones. For example, the following command only adds a DNS server and updates the route metrics
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is augment the proper term here? Normally that refers to "adding additional value/capabilities" to something.
What do you think about "join"? This way it's clear that they ultimately end up in the same option set, as if they were all provided at the same time.

of any existing route options:
<sourcecode>
PUSH_UPDATE,route 10.10.10.0 255.255.255.0,-dns
PUSH_UPDATE,dns server 0 10.10.10.1,route-metric 100
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

text indentation issue?

</sourcecode>
</t>
<t>
Options with the same name, previously pushed with <tt>PUSH_REPLY</tt> or <tt>PUSH_UPDATE</tt>, are replaced.
For instance, the following command removes all existing routes and adds two new routes:
<sourcecode>
PUSH_UPDATE,route 10.1.0.0 255.255.0.0,route 10.2.0.0 255.255.0.0
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

text indentation issue?

</sourcecode>
</t>
<t>
To remove an option, it should be prefixed with <tt>-</tt>. The following example removes all existing <tt>dns</tt> options:
<sourcecode>
PUSH_UPDATE,-dns
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

text indentation issue?

</sourcecode>
</t>
<t>
The client SHOULD support updating all pushed options; otherwise, it SHOULD reconnect. This also applies to removal.
<t>
Options prefixed with <tt>?</tt> are considered optional. The client MAY support them. If the client cannot support some optional options,
they can be ignored, and the client does not have to reconnect. This also applies to removal. Example syntax:
<sourcecode>
PUSH_UPDATE,-?block-ipv6
PUSH_UPDATE,-?block-ipv6
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

text indentation issue?

</sourcecode>
Here client should remove <tt>block-ipv6</tt> option. However, if client does not support updating it, it does not need to reconnect.
</t>
Here, the client should remove the <tt>block-ipv6</tt> option. However, if the client does not support updating it, it does not need to reconnect.
Note that the only valid syntax for removing options without reconnecting on failure is <tt>-?option-name</tt>.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can we spell out that the '-' should always come before the '?' ?

</t>
<t>
This message is only sent if the client has set the IV_PROTO_PUSH_UPDATE bit in the IV_PROTO
<xref target="peerinfo">peerinfo</xref> client variable.
</t>
</section>
</section>
<section anchor="authpending" title="AUTH_PENDING">
<t>
Format:
Expand Down