summaryrefslogtreecommitdiffstats
path: root/doc/manual/en_US/man_VBoxManage-hostonlyif.xml
blob: f2bf8c0e0dd68937be02f223b616b355aee35710 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
<?xml version="1.0" encoding="UTF-8"?>
<!--
    manpage, user manual, usage: VBoxManage hostonlyif
-->
<!--
    Copyright (C) 2006-2023 Oracle and/or its affiliates.

    This file is part of VirtualBox base platform packages, as
    available from https://www.virtualbox.org.

    This program is free software; you can redistribute it and/or
    modify it under the terms of the GNU General Public License
    as published by the Free Software Foundation, in version 3 of the
    License.

    This program is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, see <https://www.gnu.org/licenses>.

    SPDX-License-Identifier: GPL-3.0-only
-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"[
<!ENTITY % all.entities SYSTEM "all-entities.ent">
%all.entities;
]>
<refentry id="vboxmanage-hostonlyif" lang="en">
  <refentryinfo>
    <pubdate>$Date: 2023-01-17 15:15:46 +0100 (Tue, 17 Jan 2023) $</pubdate>
    <title>VBoxManage hostonlyif</title>
  </refentryinfo>

  <refmeta>
    <refentrytitle>VBoxManage-hostonlyif</refentrytitle>
    <manvolnum>1</manvolnum>
  </refmeta>

  <refnamediv>
    <refname>VBoxManage-hostonlyif</refname>
    <refpurpose>manage host-only network interfaces</refpurpose>
    <refclass>&product-name;</refclass>
  </refnamediv>

  <refsynopsisdiv>
<!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-ipconfig">
      <command>VBoxManage hostonlyif ipconfig</command>
      <arg choice="req"><replaceable>ifname</replaceable></arg>
      <group>
        <arg choice="plain">--dhcp</arg>
        <arg choice="plain">--ip=<replaceable>IPv4-address</replaceable> <arg>--netmask=<replaceable>IPv4-netmask</replaceable></arg></arg>
        <arg choice="plain">--ipv6=<replaceable>IPv6-address</replaceable> <arg>--netmasklengthv6=<replaceable>length</replaceable></arg></arg>
      </group>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-create">
      <command>VBoxManage hostonlyif create</command>
    </cmdsynopsis>

    <cmdsynopsis id="synopsis-vboxmanage-hostonlyif-remove">
      <command>VBoxManage hostonlyif remove</command>
      <arg choice="req"><replaceable>ifname</replaceable></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>
    <para>
      The <command>VBoxManage hostonlyif</command> command enables you
      to change the IP configuration of a host-only network interface.
      For a description of host-only networking, see
      <xref linkend="network_hostonly" />. Each host-only network
      interface is identified by a name and can either use the internal
      DHCP server or a manual IP configuration, both IPv4 and IPv6.
    </para>
    <refsect2 id="vboxmanage-hostonlyif-ipconfig">
      <title>Configure a Host-Only Interface</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage hostonlyif ipconfig</command> command
        configures a host-only interface.
      </para>
      <variablelist>
        <varlistentry>
          <term><replaceable>ifname</replaceable></term>
          <listitem><para>
              Specifies the name of the network interface. The name is
              of the form
              <literal>vboxnet</literal><replaceable>N</replaceable>
              where <replaceable>N</replaceable> is the interface
              instance.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--dhcp</option></term>
          <listitem><para>
              Uses DHCP for the network interface.
            </para><para>
              You cannot use this option with the <option>--ip</option>,
              <option>--ipv6</option>, <option>--netmask</option>, and
              <option>--netmasklengthv6</option> options.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--ip=<replaceable>IPv4-address</replaceable></option></term>
          <listitem><para>
              Specifies the IPv4 IP address for the network interface.
            </para><para>
              You cannot use this option with the
              <option>--dhcp</option>, <option>--ipv6</option>, and
              <option>--netmasklengthv6</option> options.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--netmask=<replaceable>IPv4-netmask</replaceable></option></term>
          <listitem><para>
              Specifies the IPv4 netmask of the network interface. The
              default value is <literal>255.255.255.0</literal>.
            </para><para>
              You can use this option only with the
              <option>--ip</option> option.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--ipv6=<replaceable>IPv6-address</replaceable></option></term>
          <listitem><para>
              Specifies the IPv6 IP address for the network interface.
            </para><para>
              You cannot use this option with the
              <option>--dhcp</option>, <option>--ip</option>, and
              <option>--netmask</option> options.
            </para></listitem>
        </varlistentry>
        <varlistentry>
          <term><option>--netmasklengthv6=<replaceable>length</replaceable></option></term>
          <listitem><para>
              Specifies the length of the IPv6 network interface. The
              default value is <literal>64</literal>.
            </para><para>
              You can use this option only with the
              <option>--ipv6</option> option.
            </para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
    <refsect2 id="vboxmanage-hostonlyif-create">
      <title>Create a Network Interface on the Host System</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage hostonlyif create</command> command
        creates a new host-only network interface on the host operating
        system (OS). The network interface name is of the form
        <literal>vboxnet</literal><replaceable>N</replaceable> where
        <replaceable>N</replaceable> is the interface instance. You must
        run this command before you can attach virtual machines (VMs) to
        the host-only network.
      </para>
    </refsect2>
    <refsect2 id="vboxmanage-hostonlyif-remove">
      <title>Remove a Network Interface From the Host System</title>
      <remark role="help-copy-synopsis"/>
      <para>
        The <command>VBoxManage hostonlyif remove</command> command
        removes the specified host-only network interface from the host
        OS.
      </para>
      <variablelist>
        <varlistentry>
          <term><replaceable>ifname</replaceable></term>
          <listitem><para>
              Specifies the name of the network interface. The name is
              of the form
              <literal>vboxnet</literal><replaceable>N</replaceable>
              where <replaceable>N</replaceable> is the interface
              instance.
            </para></listitem>
        </varlistentry>
      </variablelist>
    </refsect2>
  </refsect1>

  <refsect1>
    <title>Examples</title>
    <remark role="help-scope" condition="GLOBAL" />
    <para>
      The following command creates a new host-only network interface.
    </para>
<screen>$ VBoxManage hostonlyif create
0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100%
Interface 'vboxnet2' was successfully created</screen>
    <para>
      The following command configures the IPv4 address for the
      <literal>vboxnet2</literal> host-only network interface.
    </para>
<screen>$ VBoxManage hostonlyif ipconfig vboxnet2 --ip 10.0.2.18</screen>
  </refsect1>
</refentry>