Merge "[docs] Update header levels"
[yardstick.git] / docs / testing / user / userguide / 04-installation.rst
1 .. This work is licensed under a Creative Commons Attribution 4.0 International
2 .. License.
3 .. http://creativecommons.org/licenses/by/4.0
4 .. (c) OPNFV, Ericsson AB, Huawei Technologies Co.,Ltd and others.
5
6 ..
7    Convention for heading levels in Yardstick documentation:
8
9    =======  Heading 0 (reserved for the title in a document)
10    -------  Heading 1
11    ~~~~~~~  Heading 2
12    +++++++  Heading 3
13    '''''''  Heading 4
14
15    Avoid deeper levels because they do not render well.
16
17 ======================
18 Yardstick Installation
19 ======================
20
21
22 Yardstick supports installation by Docker or directly in Ubuntu. The
23 installation procedure for Docker and direct installation are detailed in
24 the sections below.
25
26 To use Yardstick you should have access to an OpenStack environment, with at
27 least Nova, Neutron, Glance, Keystone and Heat installed.
28
29 The steps needed to run Yardstick are:
30
31 1. Install Yardstick.
32 2. Load OpenStack environment variables.
33 3. Create Yardstick flavor.
34 4. Build a guest image and load it into the OpenStack environment.
35 5. Create the test configuration ``.yaml`` file and run the test case/suite.
36
37
38 Prerequisites
39 -------------
40
41 The OPNFV deployment is out of the scope of this document and can be found in
42 `User Guide & Configuration Guide`_. The OPNFV platform is considered as the
43 System Under Test (SUT) in this document.
44
45 Several prerequisites are needed for Yardstick:
46
47 1. A Jumphost to run Yardstick on
48 2. A Docker daemon or a virtual environment installed on the Jumphost
49 3. A public/external network created on the SUT
50 4. Connectivity from the Jumphost to the SUT public/external network
51
52 .. note:: *Jumphost* refers to any server which meets the previous
53    requirements. Normally it is the same server from where the OPNFV
54    deployment has been triggered.
55
56 .. warning:: Connectivity from Jumphost is essential and it is of paramount
57    importance to make sure it is working before even considering to install
58    and run Yardstick. Make also sure you understand how your networking is
59    designed to work.
60
61 .. note:: If your Jumphost is operating behind a company http proxy and/or
62    Firewall, please first consult `Proxy Support`_ section which is towards
63    the end of this document. That section details some tips/tricks which *may*
64    be of help in a proxified environment.
65
66
67 Install Yardstick using Docker (first option) (**recommended**)
68 ---------------------------------------------------------------
69
70 Yardstick has a Docker image. It is recommended to use this Docker image to run
71 Yardstick test.
72
73 Prepare the Yardstick container
74 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
75
76 Install docker on your guest system with the following command, if not done
77 yet::
78
79    wget -qO- https://get.docker.com/ | sh
80
81 Pull the Yardstick Docker image (``opnfv/yardstick``) from the public dockerhub
82 registry under the OPNFV account in dockerhub_, with the following docker
83 command::
84
85    sudo -EH docker pull opnfv/yardstick:stable
86
87 After pulling the Docker image, check that it is available with the
88 following docker command::
89
90    [yardsticker@jumphost ~]$ docker images
91    REPOSITORY         TAG       IMAGE ID        CREATED      SIZE
92    opnfv/yardstick    stable    a4501714757a    1 day ago    915.4 MB
93
94 Run the Docker image to get a Yardstick container::
95
96    docker run -itd --privileged -v /var/run/docker.sock:/var/run/docker.sock \
97       -p 8888:5000 --name yardstick opnfv/yardstick:stable
98
99 Description of the parameters used with ``docker run`` command
100
101   +------------------------+--------------------------------------------------+
102   | Parameters             | Detail                                           |
103   +========================+==================================================+
104   | -itd                   |  -i: interactive, Keep STDIN open even if not    |
105   |                        |  attached                                        |
106   |                        +--------------------------------------------------+
107   |                        |  -t: allocate a pseudo-TTY detached mode, in the |
108   |                        |  background                                      |
109   +------------------------+--------------------------------------------------+
110   | --privileged           | If you want to build ``yardstick-image`` in      |
111   |                        | Yardstick container, this parameter is needed    |
112   +------------------------+--------------------------------------------------+
113   | -p 8888:5000           | Redirect the a host port (8888) to a container   |
114   |                        | port (5000)                                      |
115   +------------------------+--------------------------------------------------+
116   | -v /var/run/docker.sock| If you want to use yardstick env                 |
117   | :/var/run/docker.sock  | grafana/influxdb to create a grafana/influxdb    |
118   |                        | container out of Yardstick container             |
119   +------------------------+--------------------------------------------------+
120   | --name yardstick       | The name for this container                      |
121   +------------------------+--------------------------------------------------+
122
123
124 If the host is restarted
125 ^^^^^^^^^^^^^^^^^^^^^^^^
126
127 The yardstick container must be started if the host is rebooted::
128
129     docker start yardstick
130
131 Configure the Yardstick container environment
132 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
133
134 There are three ways to configure environments for running Yardstick, explained
135 in the following sections. Before that, access the Yardstick container::
136
137    docker exec -it yardstick /bin/bash
138
139 and then configure Yardstick environments in the Yardstick container.
140
141 Using the CLI command ``env prepare`` (first way) (**recommended**)
142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
143
144 In the Yardstick container, the Yardstick repository is located in the
145 ``/home/opnfv/repos`` directory. Yardstick provides a CLI to prepare OpenStack
146 environment variables and create Yardstick flavor and guest images
147 automatically::
148
149    yardstick env prepare
150
151 .. note:: Since Euphrates release, the above command will not be able to
152   automatically configure the ``/etc/yardstick/openstack.creds`` file. So before
153   running the above command, it is necessary to create the
154   ``/etc/yardstick/openstack.creds`` file and save OpenStack environment
155   variables into it manually. If you have the openstack credential file saved
156   outside the Yardstick Docker container, you can do this easily by mapping the
157   credential file into Yardstick container using::
158
159      '-v /path/to/credential_file:/etc/yardstick/openstack.creds'
160
161   when running the Yardstick container. For details of the required OpenStack
162   environment variables please refer to section `Export OpenStack environment
163   variables`_.
164
165 The ``env prepare`` command may take up to 6-8 minutes to finish building
166 yardstick-image and other environment preparation. Meanwhile if you wish to
167 monitor the env prepare process, you can enter the Yardstick container in a new
168 terminal window and execute the following command::
169
170   tail -f /var/log/yardstick/uwsgi.log
171
172
173 Manually exporting the env variables and initializing OpenStack (second way)
174 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
175
176 Export OpenStack environment variables
177 ######################################
178
179 Before running Yardstick it is necessary to export OpenStack environment
180 variables::
181
182    source openrc
183
184 Environment variables in the ``openrc`` file have to include at least::
185
186    OS_AUTH_URL
187    OS_USERNAME
188    OS_PASSWORD
189    OS_PROJECT_NAME
190    EXTERNAL_NETWORK
191
192 A sample ``openrc`` file may look like this::
193
194   export OS_PASSWORD=console
195   export OS_PROJECT_NAME=admin
196   export OS_AUTH_URL=http://172.16.1.222:35357/v2.0
197   export OS_USERNAME=admin
198   export OS_VOLUME_API_VERSION=2
199   export EXTERNAL_NETWORK=net04_ext
200
201
202 Manual creation of Yardstick flavor and guest images
203 ####################################################
204
205 Before executing Yardstick test cases, make sure that Yardstick flavor and
206 guest image are available in OpenStack. Detailed steps about creating the
207 Yardstick flavor and building the Yardstick guest image can be found below.
208
209 Most of the sample test cases in Yardstick are using an OpenStack flavor called
210 ``yardstick-flavor`` which deviates from the OpenStack standard ``m1.tiny``
211 flavor by the disk size; instead of 1GB it has 3GB. Other parameters are the
212 same as in ``m1.tiny``.
213
214 Create ``yardstick-flavor``::
215
216    openstack flavor create --disk 3 --vcpus 1 --ram 512 --swap 100 \
217       yardstick-flavor
218
219 Most of the sample test cases in Yardstick are using a guest image called
220 ``yardstick-image`` which deviates from an Ubuntu Cloud Server image
221 containing all the required tools to run test cases supported by Yardstick.
222 Yardstick has a tool for building this custom image. It is necessary to have
223 ``sudo`` rights to use this tool.
224
225 Also you may need install several additional packages to use this tool, by
226 follwing the commands below::
227
228    sudo -EH apt-get update && sudo -EH apt-get install -y qemu-utils kpartx
229
230 This image can be built using the following command in the directory where
231 Yardstick is installed::
232
233    export YARD_IMG_ARCH='amd64'
234    echo "Defaults env_keep += \'YARD_IMG_ARCH\'" | sudo tee --append \
235       /etc/sudoers > /dev/null
236    sudo -EH tools/yardstick-img-modify tools/ubuntu-server-cloudimg-modify.sh
237
238 .. warning:: Before building the guest image inside the Yardstick container,
239   make sure the container is granted with privilege. The script will create files
240   by default in ``/tmp/workspace/yardstick`` and the files will be owned by root.
241
242 The created image can be added to OpenStack using the OpenStack client or via
243 the OpenStack Dashboard::
244
245    openstack image create --disk-format qcow2 --container-format bare \
246       --public --file /tmp/workspace/yardstick/yardstick-image.img \
247        yardstick-image
248
249
250 Some Yardstick test cases use a `Cirros 0.3.5`_ image and/or a `Ubuntu 16.04`_
251 image. Add Cirros and Ubuntu images to OpenStack::
252
253    openstack image create --disk-format qcow2 --container-format bare \
254       --public --file $cirros_image_file cirros-0.3.5
255    openstack image create --disk-format qcow2 --container-format bare \
256       --file $ubuntu_image_file Ubuntu-16.04
257
258
259 Automatic initialization of OpenStack (third way)
260 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
261
262 Similar to the second way, the first step is also to
263 `Export OpenStack environment variables`_. Then the following steps should be
264 done.
265
266 Automatic creation of Yardstick flavor and guest images
267 #######################################################
268
269 Yardstick has a script for automatically creating Yardstick flavor and building
270 Yardstick guest images. This script is mainly used for CI and can be also used
271 in the local environment::
272
273    source $YARDSTICK_REPO_DIR/tests/ci/load_images.sh
274
275
276 The Yardstick container GUI
277 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
278
279 In Euphrates release, Yardstick implemented a GUI for Yardstick Docker
280 container. After booting up Yardstick container, you can visit the GUI at
281 ``<container_host_ip>:8888/gui/index.html``.
282
283 For usage of Yardstick GUI, please watch our demo video at
284 `Yardstick GUI demo`_.
285
286 .. note:: The Yardstick GUI is still in development, the GUI layout and
287   features may change.
288
289 Delete the Yardstick container
290 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
291
292 If you want to uninstall Yardstick, just delete the Yardstick container::
293
294    sudo docker stop yardstick && docker rm yardstick
295
296
297
298 Install Yardstick directly in Ubuntu (second option)
299 ----------------------------------------------------
300
301 .. _install-framework:
302
303 Alternatively you can install Yardstick framework directly in Ubuntu or in an
304 Ubuntu Docker image. No matter which way you choose to install Yardstick, the
305 following installation steps are identical.
306
307 If you choose to use the Ubuntu Docker image, you can pull the Ubuntu
308 Docker image from Docker hub::
309
310    sudo -EH docker pull ubuntu:16.04
311
312
313 Install Yardstick
314 ^^^^^^^^^^^^^^^^^
315
316 Prerequisite preparation::
317
318    sudo -EH apt-get update && sudo -EH apt-get install -y \
319       git python-setuptools python-pip
320    sudo -EH easy_install -U setuptools==30.0.0
321    sudo -EH pip install appdirs==1.4.0
322    sudo -EH pip install virtualenv
323
324 Download the source code and install Yardstick from it::
325
326    git clone https://gerrit.opnfv.org/gerrit/yardstick
327    export YARDSTICK_REPO_DIR=~/yardstick
328    cd ~/yardstick
329    sudo -EH ./install.sh
330
331 If the host is ever restarted, nginx and uwsgi need to be restarted::
332
333    service nginx restart
334    uwsgi -i /etc/yardstick/yardstick.ini
335
336 Configure the Yardstick environment (**Todo**)
337 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
338
339 For installing Yardstick directly in Ubuntu, the ``yardstick env`` command is
340 not available. You need to prepare OpenStack environment variables and create
341 Yardstick flavor and guest images manually.
342
343
344 Uninstall Yardstick
345 ^^^^^^^^^^^^^^^^^^^
346
347 For uninstalling Yardstick, just delete the virtual environment::
348
349    rm -rf ~/yardstick_venv
350
351
352 Install Yardstick directly in OpenSUSE
353 --------------------------------------
354
355 .. _install-framework:
356
357 You can install Yardstick framework directly in OpenSUSE.
358
359
360 Install Yardstick
361 ^^^^^^^^^^^^^^^^^
362
363 Prerequisite preparation::
364
365    sudo -EH zypper -n install -y gcc \
366       wget \
367       git \
368       sshpass \
369       qemu-tools \
370       kpartx \
371       libffi-devel \
372       libopenssl-devel \
373       python \
374       python-devel \
375       python-virtualenv \
376       libxml2-devel \
377       libxslt-devel \
378       python-setuptools-git
379
380 Create a virtual environment::
381
382    virtualenv ~/yardstick_venv
383    export YARDSTICK_VENV=~/yardstick_venv
384    source ~/yardstick_venv/bin/activate
385    sudo -EH easy_install -U setuptools
386
387 Download the source code and install Yardstick from it::
388
389    git clone https://gerrit.opnfv.org/gerrit/yardstick
390    export YARDSTICK_REPO_DIR=~/yardstick
391    cd yardstick
392    sudo -EH python setup.py install
393    sudo -EH pip install -r requirements.txt
394
395 Install missing python modules::
396
397    sudo -EH pip install pyyaml \
398       oslo_utils \
399       oslo_serialization \
400       oslo_config \
401       paramiko \
402       python.heatclient \
403       python.novaclient \
404       python.glanceclient \
405       python.neutronclient \
406       scp \
407       jinja2
408
409
410 Configure the Yardstick environment
411 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
412
413 Source the OpenStack environment variables::
414
415    source DEVSTACK_DIRECTORY/openrc
416
417 Export the Openstack external network. The default installation of Devstack
418 names the external network public::
419
420    export EXTERNAL_NETWORK=public
421    export OS_USERNAME=demo
422
423 Change the API version used by Yardstick to v2.0 (the devstack openrc sets it
424 to v3)::
425
426    export OS_AUTH_URL=http://PUBLIC_IP_ADDRESS:5000/v2.0
427
428
429 Uninstall Yardstick
430 ^^^^^^^^^^^^^^^^^^^
431
432 For unistalling Yardstick, just delete the virtual environment::
433
434    rm -rf ~/yardstick_venv
435
436
437 Verify the installation
438 -----------------------
439
440 It is recommended to verify that Yardstick was installed successfully
441 by executing some simple commands and test samples. Before executing Yardstick
442 test cases make sure ``yardstick-flavor`` and ``yardstick-image`` can be found
443 in OpenStack and the ``openrc`` file is sourced. Below is an example invocation
444 of Yardstick ``help`` command and ``ping.py`` test sample::
445
446    yardstick -h
447    yardstick task start samples/ping.yaml
448
449 .. note:: The above commands could be run in both the Yardstick container and
450   the Ubuntu directly.
451
452 Each testing tool supported by Yardstick has a sample configuration file.
453 These configuration files can be found in the ``samples`` directory.
454
455 Default location for the output is ``/tmp/yardstick.out``.
456
457
458 Automatic installation of Yardstick using ansible
459 -------------------------------------------------
460
461 Automatic installation can be used as an alternative to the manual.
462 Yardstick can be installed on the bare metal and to the container. Yardstick
463 container can be either pulled or built.
464
465 Bare metal installation
466 ^^^^^^^^^^^^^^^^^^^^^^^
467
468 Use ansible script ``install.yaml`` to install Yardstick on Ubuntu server:
469
470 .. code-block:: console
471
472     ansible-playbook -i install-inventory.ini install.yaml \
473     -e YARDSTICK_DIR=<path to Yardstick folder>
474
475 .. note:: By default ``INSTALLATION_MODE`` is ``baremetal``.
476
477 .. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to
478    Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter.
479
480 .. note:: To install Yardstick in virtual environment pass parameter
481    ``-e VIRTUAL_ENVIRONMENT=True``.
482
483 To build Yardstick NSB image pass ``IMG_PROPERTY=nsb`` as input parameter:
484
485 .. code-block:: console
486
487     ansible-playbook -i install-inventory.ini install.yaml \
488     -e IMAGE_PROPERTY=nsb \
489     -e YARDSTICK_DIR=<path to Yardstick folder>
490
491 .. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF
492    images will be built. Image type is defined by parameter ``IMAGE_PROPERTY``.
493    By default Yardstick image will be built.
494
495 Container installation
496 ^^^^^^^^^^^^^^^^^^^^^^
497
498 Use ansible script ``install.yaml`` to pull or build Yardstick
499 container. To pull Yardstick image and start container run:
500
501 .. code-block:: console
502
503     ansible-playbook -i install-inventory.ini install.yaml \
504     -e YARDSTICK_DIR=<path to Yardstick folder> \
505     -e INSTALLATION_MODE=container_pull
506
507 .. note:: In this ``INSTALLATION_MODE`` mode either Yardstick image or SampleVNF
508    images will be built. Image type is defined by variable ``IMG_PROPERTY`` in
509    file ``ansible/group_vars/all.yml``. By default Yardstick image will be
510    built.
511
512 .. note:: Open question: How to know if Docker image is built on Ubuntu 16.04 and 18.04?
513    Do we need separate tag to be used?
514
515 To build Yardstick image run:
516
517 .. code-block:: console
518
519     ansible-playbook -i install-inventory.ini install.yaml \
520     -e YARDSTICK_DIR=<path to Yardstick folder> \
521     -e INSTALLATION_MODE=container
522
523 .. note:: In this ``INSTALLATION_MODE`` mode neither Yardstick image nor SampleVNF
524    image will be built.
525
526 .. note:: By default Ubuntu 16.04 is chosen (xenial). It can be changed to
527    Ubuntu 18.04 (bionic) by passing ``-e OS_RELEASE=bionic`` parameter.
528
529 Parameters for ``install.yaml``
530 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
531
532 Description of the parameters used with ``install.yaml`` script
533
534   +-------------------------+-------------------------------------------------+
535   | Parameters              | Detail                                          |
536   +=========================+=================================================+
537   | -i install-inventory.ini| Installs package dependency to remote servers   |
538   |                         | Mandatory parameter                             |
539   |                         | By default no remote servers are provided       |
540   |                         | Needed packages will be installed on localhost  |
541   +-------------------------+-------------------------------------------------+
542   | -e YARDSTICK_DIR        | Path to Yardstick folder                        |
543   |                         | Mandatory parameter                             |
544   +-------------------------+-------------------------------------------------+
545   | -e INSTALLATION_MODE    | baremetal: Yardstick is installed to the bare   |
546   |                         | metal                                           |
547   |                         | Default parameter                               |
548   |                         +-------------------------------------------------+
549   |                         | container: Yardstick is installed in container  |
550   |                         | Container is built from Dockerfile              |
551   |                         +-------------------------------------------------+
552   |                         | container_pull: Yardstick is installed in       |
553   |                         | container                                       |
554   |                         | Container is pulled from docker hub             |
555   +-------------------------+-------------------------------------------------+
556   | -e OS_RELEASE           | xenial or bionic: Ubuntu version to be used     |
557   |                         | Default is Ubuntu 16.04 (xenial)                |
558   +-------------------------+-------------------------------------------------+
559   | -e IMAGE_PROPERTY       | normal or nsb: Type of the VM image to be built |
560   |                         | Default image is Yardstick                      |
561   +-------------------------+-------------------------------------------------+
562   | -e VIRTUAL_ENVIRONMENT  | False or True: Whether install in virtualenv    |
563   |                         | Default is False                                |
564   +-------------------------+-------------------------------------------------+
565
566
567 Deploy InfluxDB and Grafana using Docker
568 ----------------------------------------
569
570 Without InfluxDB, Yardstick stores results for running test case in the file
571 ``/tmp/yardstick.out``. However, it's inconvenient to retrieve and display
572 test results. So we will show how to use InfluxDB to store data and use
573 Grafana to display data in the following sections.
574
575 Automatic deployment of InfluxDB and Grafana containers (**recommended**)
576 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
577
578 Firstly, enter the Yardstick container::
579
580    sudo -EH docker exec -it yardstick /bin/bash
581
582 Secondly, create InfluxDB container and configure with the following command::
583
584    yardstick env influxdb
585
586 Thirdly, create and configure Grafana container::
587
588    yardstick env grafana
589
590 Then you can run a test case and visit http://host_ip:1948
591 (``admin``/``admin``) to see the results.
592
593 .. note:: Executing ``yardstick env`` command to deploy InfluxDB and Grafana
594   requires Jumphost's docker API version => 1.24. Run the following command to
595   check the docker API version on the Jumphost::
596
597     docker version
598
599
600 Manual deployment of InfluxDB and Grafana containers
601 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
602
603 You can also deploy influxDB and Grafana containers manually on the Jumphost.
604 The following sections show how to do.
605
606 Pull docker images::
607
608    sudo -EH docker pull tutum/influxdb
609    sudo -EH docker pull grafana/grafana
610
611 Run influxDB::
612
613    sudo -EH docker run -d --name influxdb \
614       -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 \
615       tutum/influxdb
616    docker exec -it influxdb bash
617
618 Configure influxDB::
619
620    influx
621       >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
622       >CREATE DATABASE yardstick;
623       >use yardstick;
624       >show MEASUREMENTS;
625
626 Run Grafana::
627
628    sudo -EH docker run -d --name grafana -p 1948:3000 grafana/grafana
629
630 Log on http://{YOUR_IP_HERE}:1948 using ``admin``/``admin`` and configure
631 database resource to be ``{YOUR_IP_HERE}:8086``.
632
633 .. image:: images/Grafana_config.png
634    :width: 800px
635    :alt: Grafana data source configuration
636
637 Configure ``yardstick.conf``::
638
639    sudo -EH docker exec -it yardstick /bin/bash
640    sudo cp etc/yardstick/yardstick.conf.sample /etc/yardstick/yardstick.conf
641    sudo vi /etc/yardstick/yardstick.conf
642
643 Modify ``yardstick.conf``::
644
645    [DEFAULT]
646    debug = True
647    dispatcher = influxdb
648
649    [dispatcher_influxdb]
650    timeout = 5
651    target = http://{YOUR_IP_HERE}:8086
652    db_name = yardstick
653    username = root
654    password = root
655
656 Now you can run Yardstick test cases and store the results in influxDB.
657
658
659 Deploy InfluxDB and Grafana directly in Ubuntu (**Todo**)
660 ---------------------------------------------------------
661
662
663 Proxy Support
664 -------------
665
666 To configure the Jumphost to access Internet through a proxy its necessary to
667 export several variables to the environment, contained in the following
668 script::
669
670    #!/bin/sh
671    _proxy=<proxy_address>
672    _proxyport=<proxy_port>
673    _ip=$(hostname -I | awk '{print $1}')
674
675    export ftp_proxy=http://$_proxy:$_proxyport
676    export FTP_PROXY=http://$_proxy:$_proxyport
677    export http_proxy=http://$_proxy:$_proxyport
678    export HTTP_PROXY=http://$_proxy:$_proxyport
679    export https_proxy=http://$_proxy:$_proxyport
680    export HTTPS_PROXY=http://$_proxy:$_proxyport
681    export no_proxy=127.0.0.1,localhost,$_ip,$(hostname),<.localdomain>
682    export NO_PROXY=127.0.0.1,localhost,$_ip,$(hostname),<.localdomain>
683
684 To enable Internet access from a container using ``docker``, depends on the OS
685 version. On Ubuntu 14.04 LTS, which uses SysVinit, ``/etc/default/docker`` must
686 be modified::
687
688    .......
689    # If you need Docker to use an HTTP proxy, it can also be specified here.
690    export http_proxy="http://<proxy_address>:<proxy_port>/"
691    export https_proxy="https://<proxy_address>:<proxy_port>/"
692
693 Then its necessary to restart the ``docker`` service::
694
695    sudo -EH service docker restart
696
697 In Ubuntu 16.04 LTS, which uses Systemd, its necessary to create a drop-in
698 directory::
699
700    sudo mkdir /etc/systemd/system/docker.service.d
701
702 Then, the proxy configuration will be stored in the following file::
703
704    # cat /etc/systemd/system/docker.service.d/http-proxy.conf
705    [Service]
706    Environment="HTTP_PROXY=https://<proxy_address>:<proxy_port>/"
707    Environment="HTTPS_PROXY=https://<proxy_address>:<proxy_port>/"
708    Environment="NO_PROXY=localhost,127.0.0.1,<localaddress>,<.localdomain>"
709
710 The changes need to be flushed and the ``docker`` service restarted::
711
712    sudo systemctl daemon-reload
713    sudo systemctl restart docker
714
715 Any container is already created won't contain these modifications. If needed,
716 stop and delete the container::
717
718    sudo docker stop yardstick
719    sudo docker rm yardstick
720
721 .. warning:: Be careful, the above ``rm`` command will delete the container
722   completely. Everything on this container will be lost.
723
724 Then follow the previous instructions `Prepare the Yardstick container`_ to
725 rebuild the Yardstick container.
726
727
728 References
729 ----------
730
731 .. _`User Guide & Configuration Guide`: http://docs.opnfv.org/en/latest/release/userguide.introduction.html
732 .. _dockerhub: https://hub.docker.com/r/opnfv/yardstick/
733 .. _`Cirros 0.3.5`: http://download.cirros-cloud.net/0.3.5/cirros-0.3.5-x86_64-disk.img
734 .. _`Ubuntu 16.04`: https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-disk1.img
735 .. _`Yardstick GUI demo`: https://www.youtube.com/watch?v=M3qbJDp6QBk