VirtualBox

Opened 7 years ago

Closed 6 years ago

Last modified 6 years ago

#16912 closed enhancement (fixed)

Add network options overview section in the manual -> fixed

Reported by: Socratis Owned by:
Component: documentation Version: VirtualBox 5.1.22
Keywords: network overview, user manual Cc:
Guest type: other Host type: other

Description

There are a lot of users that are getting confused for what option to use when selecting an appropriate network. What I have found useful is to include a small table that summarizes the capabilities of each and every network mode. Something like the following:

VM <-> Host VM1 <-> VM2 VM -> Internet VM <- Internet
HostOnly + + - -
Internal - + - -
Bridged + + + +
NAT - - + Port forward
NATService - + + Port forward

Please consider adding something like that at the beginning of Ch. 6 Networking. I have a feeling it will help tremendously with the user understanding and support.

Attachments (1)

6.2 Networking overview table.pdf​ (108.6 KB ) - added by Socratis 6 years ago.
Single PDF page, showing the rendered table

Download all attachments as: .zip

Change History (11)

comment:1 by Frank Mehnert, 7 years ago

Excellent idea and done so in r68120.

comment:2 by Socratis, 7 years ago

One small correction needed. The "Port forward" link for the NATService should not point to the anchor "natforward" but to the "network_nat_service", because that's where the port forwarding for the NATService is described. Thanks. 

Index: /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml
===================================================================
--- /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml	(revision 68120)
+++ /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml	(working copy)
@@ -282,7 +282,7 @@
             <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
-            <entry><link linkend="natforward">Port forwarding</link></entry>
+            <entry><link linkend="network_nat_service">Port forwarding</link></entry>
           </row>
         </tbody>
       </tgroup>

comment:3 by Frank Mehnert, 7 years ago

Fixed. Thanks again!

comment:4 by Frank Mehnert, 7 years ago

Resolution: → fixed
Status: new → closed

Part of VBox 5.1.26.

comment:5 by Socratis, 7 years ago

Resolution: fixed
Status: closed → reopened

The table above, that actually landed in "ch. 6.2. Introduction to networking modes", has a serious flaw! You can access the host from the VM in a NAT and a NATservice mode! That needs to be addressed, we were giving the wrong impression to the users. Also, something that gets introduced is the change from "Internet" to "LAN/Int.", to reflect the fact that it's not only the Internet that a networking mode can have access to, but also the LAN where the host belongs. That was also creating a lot of confusion, they were expecting that NAT meant no LAN access, just Internet access. That also is addressed with the revised table.

So, the "VM <-> Host" column is broken in two. It's almost identical to the "VM -> LAN/Int." and the "VM <- LAN/Int.", except the HostOnly network option. That needs to stay separate, that's the big difference.

So, the new table should look something like:

VM -> Host VM <- Host VM1 <-> VM2 VM -> LAN/Int. VM <- LAN/Int.
HostOnly + + + - -
Internal - - + - -
Bridged + + + + +
NAT + Port forward - + Port forward
NATService + Port forward + + Port forward

The port forwarding rules (and their links) should be the same for NAT and NATservice, basically a copy.

A patch for r.72051 or r.72026 (72051 crashes on OSX! Oops!) will follow...

comment:6 by Socratis, 7 years ago

The following patch is provided under the MIT license. Patch was tested and verified with r. 72026. It's nothing big after all, just a column added and some headers/cells modified. 

svn diff /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml 
Index: /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml
===================================================================
--- /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml	(revision 72026)
+++ /Users/Shared/vbox/doc/manual/en_US/user_Networking.xml	(working copy)
@@ -233,7 +233,7 @@
     networking modes:</para>
     <table>
       <title>Overview</title>
-      <tgroup cols="5">
+      <tgroup cols="6">
         <colspec align="left" />
         <colspec align="center" />
         <colspec align="center" />
@@ -242,7 +242,8 @@
         <thead valign="middle">
           <row>
             <entry></entry>
-            <entry><emphasis role="bold">VM &harr; Host</emphasis></entry>
+            <entry><emphasis role="bold">VM &rarr; Host</emphasis></entry>
+            <entry><emphasis role="bold">VM &larr; Host</emphasis></entry>
             <entry><emphasis role="bold">VM1 &harr; VM2</emphasis></entry>
             <entry><emphasis role="bold">VM &rarr; Internet</emphasis></entry>
             <entry><emphasis role="bold">VM &larr; Internet</emphasis></entry>
@@ -252,6 +253,7 @@
           <row>
             <entry>Host-only</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
             <entry align="center"><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -259,6 +261,7 @@
           <row>
             <entry>Internal</entry>
             <entry>&ndash;</entry>
+            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -269,19 +272,22 @@
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
           </row>
           <row>
             <entry>NAT</entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="natforward">Port forwarding</link></entry>
             <entry>&ndash;</entry>
-            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><link linkend="natforward">Port forwarding</link></entry>
           </row>
           <row>
             <entry>NAT Network</entry>
-            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="network_nat_service">Port forwarding</link></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
             <entry><link linkend="network_nat_service">Port forwarding</link></entry>
           </row>
         </tbody>

BTW, I tried everything I could think of to make that little rascal align the "+" and the "-" in the center of the column... Spectacular failure! :D

Maybe I don't know enough about the syntax, although it really seemed straight forward, it was completely ignored. Oh well...

Oh, and you might want to take down the font size a dash on the table. In its PDF format, you get wrapping within the cells. It would be best if avoided, but as I said, I don't know too much about the doxygen syntax and I didn't want to mess things up...

comment:7 by Socratis, 7 years ago

New patch, provided under the MIT license. This one "fixes" the wrapping in the column headers, by removing the spaces in between the "direction arrows". Tested and works as advertised in the PDF version. 

Index: doc/manual/en_US/user_Networking.xml
===================================================================
--- doc/manual/en_US/user_Networking.xml	(revision 72142)
+++ doc/manual/en_US/user_Networking.xml	(working copy)
@@ -233,7 +233,7 @@
     networking modes:</para>
     <table>
       <title>Overview</title>
-      <tgroup cols="5">
+      <tgroup cols="6">
         <colspec align="left" />
         <colspec align="center" />
         <colspec align="center" />
@@ -242,16 +242,18 @@
         <thead valign="middle">
           <row>
             <entry></entry>
-            <entry><emphasis role="bold">VM &harr; Host</emphasis></entry>
-            <entry><emphasis role="bold">VM1 &harr; VM2</emphasis></entry>
-            <entry><emphasis role="bold">VM &rarr; Internet</emphasis></entry>
-            <entry><emphasis role="bold">VM &larr; Internet</emphasis></entry>
+            <entry><emphasis role="bold">VM&rarr;Host</emphasis></entry>
+            <entry><emphasis role="bold">VM&larr;Host</emphasis></entry>
+            <entry><emphasis role="bold">VM1&harr;VM2</emphasis></entry>
+            <entry><emphasis role="bold">VM&rarr;Net/LAN</emphasis></entry>
+            <entry><emphasis role="bold">VM&larr;Net/LAN</emphasis></entry>
           </row>
         </thead>
         <tbody valign="middle">
           <row>
             <entry>Host-only</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
             <entry align="center"><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -259,6 +261,7 @@
           <row>
             <entry>Internal</entry>
             <entry>&ndash;</entry>
+            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -269,19 +272,22 @@
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
           </row>
           <row>
             <entry>NAT</entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="natforward">Port forwarding</link></entry>
             <entry>&ndash;</entry>
-            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><link linkend="natforward">Port forwarding</link></entry>
           </row>
           <row>
-            <entry>NAT Network</entry>
-            <entry>&ndash;</entry>
+            <entry>NAT service</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="network_nat_service">Port forwarding</link></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
             <entry><link linkend="network_nat_service">Port forwarding</link></entry>
           </row>
         </tbody>

by Socratis, 6 years ago

Attachment: 6.2 Networking overview table.pdf​ added

Single PDF page, showing the rendered table

comment:8 by Socratis, 6 years ago

Revisiting the issue after ticket #17913 was filed (a duplicate of this one). What I'm adding now is the rendered PDF page with the changes. I did some small modification (yet again ;)) so that the PDF table would render a little bit nicer. 

Index: doc/manual/en_US/user_Networking.xml
===================================================================
--- doc/manual/en_US/user_Networking.xml	(revision 74182)
+++ doc/manual/en_US/user_Networking.xml	(working copy)
@@ -291,19 +291,21 @@
 
     <table id="table-networking-modes">
       <title>Overview of Networking Modes</title>
-      <tgroup cols="5">
+      <tgroup cols="6">
         <colspec align="left" />
         <colspec align="center" />
         <colspec align="center" />
         <colspec align="center" />
         <colspec align="center" />
+        <colspec align="center" />
         <thead valign="middle">
           <row>
             <entry></entry>
-            <entry><emphasis role="bold">VM &harr; Host</emphasis></entry>
-            <entry><emphasis role="bold">VM1 &harr; VM2</emphasis></entry>
-            <entry><emphasis role="bold">VM &rarr; Internet</emphasis></entry>
-            <entry><emphasis role="bold">VM &larr; Internet</emphasis></entry>
+            <entry><emphasis role="bold">VM&rarr;Host</emphasis></entry>
+            <entry><emphasis role="bold">VM&larr;Host</emphasis></entry>
+            <entry><emphasis role="bold">VM1&harr;VM2</emphasis></entry>
+            <entry><emphasis role="bold">VM&rarr;Net/LAN</emphasis></entry>
+            <entry><emphasis role="bold">VM&larr;Net/LAN</emphasis></entry>
           </row>
         </thead>
         <tbody valign="middle">
@@ -310,6 +312,7 @@
           <row>
             <entry>Host-only</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
             <entry align="center"><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -317,6 +320,7 @@
           <row>
             <entry>Internal</entry>
             <entry>&ndash;</entry>
+            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry>&ndash;</entry>
             <entry>&ndash;</entry>
@@ -327,20 +331,23 @@
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
           </row>
           <row>
             <entry>NAT</entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="natforward">Port forward</link></entry>
             <entry>&ndash;</entry>
-            <entry>&ndash;</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
-            <entry><link linkend="natforward">Port forwarding</link></entry>
+            <entry><link linkend="natforward">Port forward</link></entry>
           </row>
           <row>
-            <entry>NAT Network</entry>
-            <entry>&ndash;</entry>
+            <entry>NATservice</entry>
             <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="network_nat_service">Port forward</link></entry>
             <entry><emphasis role="bold">+</emphasis></entry>
-            <entry><link linkend="network_nat_service">Port forwarding</link></entry>
+            <entry><emphasis role="bold">+</emphasis></entry>
+            <entry><link linkend="network_nat_service">Port forward</link></entry>
           </row>
         </tbody>
       </tgroup>
Last edited 6 years ago by Socratis (previous) (diff)

comment:9 by Michael Thayer, 6 years ago

Resolution: → fixed
Status: reopened → closed
Summary: Add network options overview section in the manual → Add network options overview section in the manual -> fixed

Committed, thanks.

comment:10 by Socratis, 6 years ago

Thanks Michael, if you could also close #17913 as a duplicate as well...

Note: See TracTickets for help on using tickets.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette