README.md 6.56 KB
Newer Older
1 2 3
CoAP Testing Tool:
------------------

Federico Sismondi's avatar
Federico Sismondi committed
4
This repo contains all necessary software (and their dependencies) for running a
5 6 7 8 9 10 11 12 13 14 15
CoAP interoperability test session.

This can be run as standalone software and also integrated to f-interop 
architecture.

### TODO
- add feat for handling step by step analysis
- document isntallation of requirements and dependencies

### CoAP Testing tools components

Federico Sismondi's avatar
Federico Sismondi committed
16 17 18
The CoAP testing tool handles the coordination, sniffing, dissection
and analysis of traces for the tests described in the test description.
The implemented test description is based on:
19 20 21 22
[ETSI CoAP test description](http://www.etsi.org/plugtests/CoAP/Document/CoAP_TestDescriptions_v015.pdf)

For description of components please visit: [f-interop doc](doc.f-interop.eu)

23 24 25

-----------------------------------------------------------------------------

Federico Sismondi's avatar
doc++  
Federico Sismondi committed
26 27
### Clonning the project
```
Federico Sismondi's avatar
Federico Sismondi committed
28
git clone --recursive https://gitlab.f-interop.eu/f-interop-contributors/coap_testing_tool.git
29
cd coap_testing_tool
Federico Sismondi's avatar
doc++  
Federico Sismondi committed
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
### Attention with the git submodules!

remember when cloning a project with submodules to use --recursive flag
```
git clone --recursive ...
```

or else (in case you forgot about the flag), right after cloning you can:
```
git submodule update --init --recursive
```

whenever you find that your utils libraries are not the latests versions
you can 'bring' those last changes from the main utils repo to your project
with:
```
git submodule update --remote --merge
```

after bringing the last changes you can update your project with the last changes by doing:
```
git add <someSubModuleDir>
git commit -m 'updated submodule reference to last commit'
git push
```

58
### Running CoAP testing tool as standalone mode
59

60
(# TODO talk about the CLI, without it you cannot run a session)
61

Federico Sismondi's avatar
Federico Sismondi committed
62
First thing needed is to have the rabbit running ;)
63
For this, you need a server running RabbitMQ message broker for handling the
64
messaging between the components taking part in your test session.
65

66 67 68 69 70 71 72 73 74 75 76
The options for this are:

- install locally RabbitMQ message broker on local machine,
create RMQ vhost, user, pass on local machine

    (# TODO add instructions)

- Request a remote vhost and its user, pass credentials to F-Interop developers.

    for this contact federico.sismondi@inria.fr or remy.leone@inria.fr

77 78 79
after having a created vhost with its user/password,
export in the machine where the testing tool is running the following
env vars:
80 81

    ```
Federico Sismondi's avatar
Federico Sismondi committed
82
    export AMQP_URL='amqp://someUser:somePassword@server/amqp_vhost'
Federico Sismondi's avatar
Federico Sismondi committed
83
    export AMQP_EXCHANGE='amq.topic'
84 85
    ```

86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
---
#### Building & running the tool
Now, let's get the testing tool running. Several approaches can be used,
these are:

( tested with debian based OS & macos )

**1.** Build the testing tool using docker (see Dockerfile) &
run the testing tool inside a docker container (recommended)

**2.** Install dependencies with ansible in the local machine &
run the testing tool using supervisor.
(no agent can be run in the same machine after)

**3.** Install dependencies with ansible in remote machine &
run the testing tool using supervisor.

**4.** Install everything manually, why not right?

---

107
#### Opt 1 - Building & running CoAP testing tool with docker (recommended)
108 109 110 111 112 113 114 115

First, let's install docker. For this just follow this instructions:

https://docs.docker.com/engine/installation/

Don't forget to start it!

Second, **build** the testing tool, from inside coap_testing_tool dir run:
116 117 118 119 120 121
```
make docker-build-all # build all tools, TT and automated-iuts
```

or run the docker build manually

122
```
Federico Sismondi's avatar
Federico Sismondi committed
123
docker build -t testing_tool-interoperability-coap .
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
for running the coap-testing-tool do
```
make run-coap-testing-tool
```

for verifying that TT is actually running:
```
make get-logs
```

Also, if you are running a session alone (no 2nd user) then you may
want to use one of the automated-iut or reference implementations,
for this, if you are testing your coap server:

```
make run-coap-client
```

or (if you are testing your coap client)
```
run-coap-server
```


150 151 152
If build fails due to a "Failed to fetch http://archive.ubuntu ...."
then:
```
Federico Sismondi's avatar
Federico Sismondi committed
153
docker build -t testing_tool-interoperability-coap . --no-cache
154 155
```

156 157
Go to FAQ, for known errors.

158
for running coap_testing_tool manually from docker api:
Federico Sismondi's avatar
Federico Sismondi committed
159

160
```
Federico Sismondi's avatar
Federico Sismondi committed
161
docker run -it
Federico Sismondi's avatar
Federico Sismondi committed
162 163 164 165 166
    --env AMQP_EXCHANGE=$AMQP_EXCHANGE
    --env AMQP_URL=$AMQP_URL
    --sysctl net.ipv6.conf.all.disable_ipv6=0
    --privileged
    testing_tool-interoperability-coap
167 168
```

169 170 171

alternatively, if you are curious and you want to know
what's under the hood:
Federico Sismondi's avatar
Federico Sismondi committed
172

173
```
Federico Sismondi's avatar
Federico Sismondi committed
174 175 176 177 178 179 180 181
docker run -it
    --env AMQP_EXCHANGE=$AMQP_EXCHANGE
    --env AMQP_URL=$AMQP_URL
    --sysctl net.ipv6.conf.all.disable_ipv6=0
    --privileged
    testing_tool-interoperability-coap
    bash

182 183 184 185 186 187 188 189 190 191 192 193
root@bab3b2220510:/coap_testing_tool# supervisord -c supervisor.conf
root@bab3b2220510:/coap_testing_tool# supervisorctl -c supervisor.conf
agent                            RUNNING   pid 28, uptime 0:00:02
automated-iut                    STARTING
bootstrap-agent-TT               RUNNING   pid 19, uptime 0:00:02
packet-router                    RUNNING   pid 24, uptime 0:00:02
packet-sniffer                   RUNNING   pid 18, uptime 0:00:02
tat                              RUNNING   pid 17, uptime 0:00:02
test-coordinator                 RUNNING   pid 26, uptime 0:00:02
supervisor>
```

194 195
Run the CLI & Agent and you are ready to launch CoAP tests from your PC!

196

197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
#### Opt 2 & 3 - Build CoAP testing tool with ansible


First thing, install ansible:

http://docs.ansible.com/ansible/intro_installation.html


Install supervisor (needed for spawning and monitoring processes):
For this follow this instructions:

http://supervisord.org/installing.html

  
Now, let's install the testing tool requirements:

**for Opt 2 (local install)**:

- change in ansible/main.yml the variable unix_user from f-interop to your
unix user, then run ansible script:

    ```
Federico Sismondi's avatar
Federico Sismondi committed
219 220
    ansible-playbook -i ansible/hosts.local ansible/main.yml
        --ask-become-pass
221 222
    ```

223
- run CoAP testing tool and monitor processes
Federico Sismondi's avatar
Federico Sismondi committed
224
    
225
    ```
226 227
    sudo -E supervisord -c supervisor.conf
    sudo supervisorctl -c supervisor.conf
228
    ```
Federico Sismondi's avatar
Federico Sismondi committed
229 230
	note: use -E when launching supervisor process, it preserves the
	env vars
231

232
Run the CLI & Agent and you are ready to launch CoAP tests from your PC!
233

234
**for Opt 3 (remote install)**:
235

236 237 238 239 240 241 242 243 244 245 246
TDB

FAQ
---

- I have my own CoAP implementation, how can I add it as an
automated-IUT into CoAP Testing Tool

    **TBD**

- Docker build returns a "cannot fetch package" or a "cannot resolve .."
Federico Sismondi's avatar
Federico Sismondi committed
247 248
    -> try using --no-cache for the docker build
    -> more info http://stackoverflow.com/questions/24991136/docker-build-could-not-resolve-archive-ubuntu-com-apt-get-fails-to-install-a