README.md 5.9 KB
Newer Older
Federico Sismondi's avatar
Federico Sismondi committed
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
Federico Sismondi's avatar
Federico Sismondi committed
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:
Federico Sismondi's avatar
Federico Sismondi committed
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
```
28
git clone --recursive https://gitlab.f-interop.eu/fsismondi/coap_testing_tool.git
29
cd coap_testing_tool
Federico Sismondi's avatar
doc++    
Federico Sismondi committed
30
```
Federico Sismondi's avatar
Federico Sismondi committed
31

32
### Running CoAP testing tool as standalone mode
Federico Sismondi's avatar
Federico Sismondi committed
33

34
(# TODO talk about the CLI, without it you cannot run a session)
Federico Sismondi's avatar
Federico Sismondi committed
35

Federico Sismondi's avatar
fix doc    
Federico Sismondi committed
36
First thing needed is to have the rabbit running ;)
37
For this, you need a server running RabbitMQ message broker for handling the
38
messaging between the components taking part in your test session.
Federico Sismondi's avatar
Federico Sismondi committed
39

40
41
42
43
44
45
46
47
48
49
50
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

51
52
53
after having a created vhost with its user/password,
export in the machine where the testing tool is running the following
env vars:
Federico Sismondi's avatar
Federico Sismondi committed
54
55

    ```
Federico Sismondi's avatar
Federico Sismondi committed
56
    export AMQP_URL='amqp://someUser:somePassword@server/amqp_vhost'
Federico Sismondi's avatar
fix doc    
Federico Sismondi committed
57
    export AMQP_EXCHANGE='amq.topic'
Federico Sismondi's avatar
Federico Sismondi committed
58
59
    ```

60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
---
#### 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?

---

81
#### Opt 1 - Building & running CoAP testing tool with docker (recommended)
82
83
84
85
86
87
88
89

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:
90
91
92
93
94
95
```
make docker-build-all # build all tools, TT and automated-iuts
```

or run the docker build manually

96
```
Federico Sismondi's avatar
Federico Sismondi committed
97
docker build -t testing_tool-interoperability-coap .
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
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
```


124
125
126
If build fails due to a "Failed to fetch http://archive.ubuntu ...."
then:
```
Federico Sismondi's avatar
Federico Sismondi committed
127
docker build -t testing_tool-interoperability-coap . --no-cache
128
129
```

130
131
Go to FAQ, for known errors.

132
for running coap_testing_tool manually from docker api:
Federico Sismondi's avatar
Federico Sismondi committed
133

134
```
Federico Sismondi's avatar
Federico Sismondi committed
135
docker run -it
Federico Sismondi's avatar
Federico Sismondi committed
136
137
138
139
140
    --env AMQP_EXCHANGE=$AMQP_EXCHANGE
    --env AMQP_URL=$AMQP_URL
    --sysctl net.ipv6.conf.all.disable_ipv6=0
    --privileged
    testing_tool-interoperability-coap
141
142
```

143
144
145

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

147
```
Federico Sismondi's avatar
Federico Sismondi committed
148
149
150
151
152
153
154
155
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

156
157
158
159
160
161
162
163
164
165
166
167
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>
```

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

170

171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
#### 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
193
194
    ansible-playbook -i ansible/hosts.local ansible/main.yml
        --ask-become-pass
195
196
    ```

Federico Sismondi's avatar
Federico Sismondi committed
197
- run CoAP testing tool and monitor processes
Federico Sismondi's avatar
Federico Sismondi committed
198
    
Federico Sismondi's avatar
Federico Sismondi committed
199
    ```
200
201
    sudo -E supervisord -c supervisor.conf
    sudo supervisorctl -c supervisor.conf
Federico Sismondi's avatar
Federico Sismondi committed
202
    ```
Federico Sismondi's avatar
Federico Sismondi committed
203
204
	note: use -E when launching supervisor process, it preserves the
	env vars
Federico Sismondi's avatar
Federico Sismondi committed
205

206
Run the CLI & Agent and you are ready to launch CoAP tests from your PC!
Federico Sismondi's avatar
Federico Sismondi committed
207

208
**for Opt 3 (remote install)**:
Federico Sismondi's avatar
Federico Sismondi committed
209

210
211
212
213
214
215
216
217
218
219
220
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
221
222
    -> 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