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