# Examples
This guide provides practical examples for common Sarin use cases.
## Table of Contents
- [Basic Usage](#basic-usage)
- [Request-Based vs Duration-Based Tests](#request-based-vs-duration-based-tests)
- [Dynamic Requests with Templating](#dynamic-requests-with-templating)
- [Headers, Cookies, and Parameters](#headers-cookies-and-parameters)
- [Request Bodies](#request-bodies)
- [Using Proxies](#using-proxies)
- [Output Formats](#output-formats)
- [Docker Usage](#docker-usage)
- [Dry Run Mode](#dry-run-mode)
- [Show Configuration](#show-configuration)
---
## Basic Usage
Send 1000 GET requests with 10 concurrent workers:
```sh
sarin -U http://example.com -r 1000 -c 10
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
```
Send requests with a custom timeout:
```sh
sarin -U http://example.com -r 1000 -c 10 -T 5s
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
timeout: 5s
```
## Request-Based vs Duration-Based Tests
**Request-based:** Stop after sending a specific number of requests:
```sh
sarin -U http://example.com -r 10000 -c 50
```
YAML equivalent
```yaml
url: http://example.com
requests: 10000
concurrency: 50
```
**Duration-based:** Run for a specific amount of time:
```sh
sarin -U http://example.com -d 5m -c 50
```
YAML equivalent
```yaml
url: http://example.com
duration: 5m
concurrency: 50
```
**Combined:** Stop when either limit is reached first:
```sh
sarin -U http://example.com -r 100000 -d 2m -c 100
```
YAML equivalent
```yaml
url: http://example.com
requests: 100000
duration: 2m
concurrency: 100
```
## Dynamic Requests with Templating
Generate a random User-Agent for each request:
```sh
sarin -U http://example.com -r 1000 -c 10 \
-H "User-Agent: {{ fakeit_UserAgent }}"
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
headers:
User-Agent: "{{ fakeit_UserAgent }}"
```
Send requests with random user data:
```sh
sarin -U http://example.com/api/users -r 1000 -c 10 \
-M POST \
-H "Content-Type: application/json" \
-B '{"name": "{{ fakeit_Name }}", "email": "{{ fakeit_Email }}"}'
```
YAML equivalent
```yaml
url: http://example.com/api/users
requests: 1000
concurrency: 10
method: POST
headers:
Content-Type: application/json
body: '{"name": "{{ fakeit_Name }}", "email": "{{ fakeit_Email }}"}'
```
Use values to share generated data across headers and body:
```sh
sarin -U http://example.com/api/users -r 1000 -c 10 \
-M POST \
-V "ID={{ fakeit_UUID }}" \
-H "X-Request-ID: {{ .Values.ID }}" \
-B '{"id": "{{ .Values.ID }}", "name": "{{ fakeit_Name }}"}'
```
YAML equivalent
```yaml
url: http://example.com/api/users
requests: 1000
concurrency: 10
method: POST
values: "ID={{ fakeit_UUID }}"
headers:
X-Request-ID: "{{ .Values.ID }}"
body: '{"id": "{{ .Values.ID }}", "name": "{{ fakeit_Name }}"}'
```
Generate random IPs and timestamps:
```sh
sarin -U http://example.com/api/logs -r 500 -c 20 \
-M POST \
-H "Content-Type: application/json" \
-B '{"ip": "{{ fakeit_IPv4Address }}", "timestamp": "{{ fakeit_Date }}", "action": "{{ fakeit_HackerVerb }}"}'
```
YAML equivalent
```yaml
url: http://example.com/api/logs
requests: 500
concurrency: 20
method: POST
headers:
Content-Type: application/json
body: '{"ip": "{{ fakeit_IPv4Address }}", "timestamp": "{{ fakeit_Date }}", "action": "{{ fakeit_HackerVerb }}"}'
```
> For the complete list of 320+ template functions, see the **[Templating Guide](templating.md)**.
## Headers, Cookies, and Parameters
**Custom headers:**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-H "Authorization: Bearer token123" \
-H "X-Custom-Header: value"
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
headers:
Authorization: Bearer token123
X-Custom-Header: value
```
**Random headers from multiple values:**
> **Note:** When multiple values are provided for the same header, Sarin starts at a random index and cycles through all values in order. Once the cycle completes, it picks a new random starting point. This ensures all values are used while maintaining some randomness.
```sh
sarin -U http://example.com -r 1000 -c 10 \
-H "X-Region: us-east" \
-H "X-Region: us-west" \
-H "X-Region: eu-central"
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
headers:
X-Region:
- us-east
- us-west
- eu-central
```
**Query parameters:**
```sh
sarin -U http://example.com/search -r 1000 -c 10 \
-P "query=test" \
-P "limit=10"
```
YAML equivalent
```yaml
url: http://example.com/search
requests: 1000
concurrency: 10
params:
query: test
limit: "10"
```
**Dynamic query parameters:**
```sh
sarin -U http://example.com/users -r 1000 -c 10 \
-P "id={{ fakeit_IntRange 1 1000 }}" \
-P "fields=name,email"
```
YAML equivalent
```yaml
url: http://example.com/users
requests: 1000
concurrency: 10
params:
id: "{{ fakeit_IntRange 1 1000 }}"
fields: name,email
```
**Cookies:**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-C "session_id=abc123" \
-C "user_id={{ fakeit_UUID }}"
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
cookies:
session_id: abc123
user_id: "{{ fakeit_UUID }}"
```
## Request Bodies
**Simple JSON body:**
```sh
sarin -U http://example.com/api/data -r 1000 -c 10 \
-M POST \
-H "Content-Type: application/json" \
-B '{"key": "value"}'
```
YAML equivalent
```yaml
url: http://example.com/api/data
requests: 1000
concurrency: 10
method: POST
headers:
Content-Type: application/json
body: '{"key": "value"}'
```
**Multiple bodies (randomly cycled):**
```sh
sarin -U http://example.com/api/products -r 1000 -c 10 \
-M POST \
-H "Content-Type: application/json" \
-B '{"product": "laptop", "price": 999}' \
-B '{"product": "phone", "price": 599}' \
-B '{"product": "tablet", "price": 399}'
```
YAML equivalent
```yaml
url: http://example.com/api/products
requests: 1000
concurrency: 10
method: POST
headers:
Content-Type: application/json
body:
- '{"product": "laptop", "price": 999}'
- '{"product": "phone", "price": 599}'
- '{"product": "tablet", "price": 399}'
```
**Dynamic body with fake data:**
```sh
sarin -U http://example.com/api/orders -r 1000 -c 10 \
-M POST \
-H "Content-Type: application/json" \
-B '{
"order_id": "{{ fakeit_UUID }}",
"customer": "{{ fakeit_Name }}",
"email": "{{ fakeit_Email }}",
"amount": {{ fakeit_Price 10 500 }},
"currency": "{{ fakeit_CurrencyShort }}"
}'
```
YAML equivalent
```yaml
url: http://example.com/api/orders
requests: 1000
concurrency: 10
method: POST
headers:
Content-Type: application/json
body: |
{
"order_id": "{{ fakeit_UUID }}",
"customer": "{{ fakeit_Name }}",
"email": "{{ fakeit_Email }}",
"amount": {{ fakeit_Price 10 500 }},
"currency": "{{ fakeit_CurrencyShort }}"
}
```
**Multipart form data:**
```sh
sarin -U http://example.com/api/upload -r 1000 -c 10 \
-M POST \
-B '{{ body_FormData (dict_Str "username" "john" "email" "john@example.com") }}'
```
YAML equivalent
```yaml
url: http://example.com/api/upload
requests: 1000
concurrency: 10
method: POST
body: '{{ body_FormData (dict_Str "username" "john" "email" "john@example.com") }}'
```
**Multipart form data with dynamic values:**
```sh
sarin -U http://example.com/api/users -r 1000 -c 10 \
-M POST \
-B '{{ body_FormData (dict_Str "name" (fakeit_Name) "email" (fakeit_Email) "phone" (fakeit_Phone)) }}'
```
YAML equivalent
```yaml
url: http://example.com/api/users
requests: 1000
concurrency: 10
method: POST
body: '{{ body_FormData (dict_Str "name" (fakeit_Name) "email" (fakeit_Email) "phone" (fakeit_Phone)) }}'
```
> **Note:** `body_FormData` automatically sets the `Content-Type` header to `multipart/form-data` with the appropriate boundary.
## Using Proxies
**Single HTTP proxy:**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-X http://proxy.example.com:8080
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
proxy: http://proxy.example.com:8080
```
**SOCKS5 proxy:**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-X socks5://proxy.example.com:1080
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
proxy: socks5://proxy.example.com:1080
```
**Multiple proxies (load balanced):**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-X http://proxy1.example.com:8080 \
-X http://proxy2.example.com:8080 \
-X socks5://proxy3.example.com:1080
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
proxy:
- http://proxy1.example.com:8080
- http://proxy2.example.com:8080
- socks5://proxy3.example.com:1080
```
**Proxy with authentication:**
```sh
sarin -U http://example.com -r 1000 -c 10 \
-X http://user:password@proxy.example.com:8080
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
proxy: http://user:password@proxy.example.com:8080
```
## Output Formats
**Table output (default):**
```sh
sarin -U http://example.com -r 1000 -c 10 -o table
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
output: table
```
**JSON output (useful for parsing):**
```sh
sarin -U http://example.com -r 1000 -c 10 -o json
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
output: json
```
**YAML output:**
```sh
sarin -U http://example.com -r 1000 -c 10 -o yaml
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
output: yaml
```
**No output (minimal memory usage):**
```sh
sarin -U http://example.com -r 1000 -c 10 -o none
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
output: none
```
**Quiet mode (hide progress bar):**
```sh
sarin -U http://example.com -r 1000 -c 10 -q
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
quiet: true
```
## Docker Usage
**Basic Docker usage:**
```sh
docker run --rm aykhans/sarin -U http://example.com -r 1000 -c 10
```
**With local config file:**
```sh
docker run --rm -v $(pwd)/config.yaml:/config.yaml aykhans/sarin -f /config.yaml
```
**With remote config file:**
```sh
docker run --rm aykhans/sarin -f https://example.com/config.yaml
```
**Interactive mode with TTY:**
```sh
docker run --rm -it aykhans/sarin -U http://example.com -r 1000 -c 10
```
## Dry Run Mode
Test your configuration without sending actual requests:
```sh
sarin -U http://example.com -r 10 -c 1 -z \
-H "X-Request-ID: {{ fakeit_UUID }}" \
-B '{"user": "{{ fakeit_Name }}"}'
```
YAML equivalent
```yaml
url: http://example.com
requests: 10
concurrency: 1
dryRun: true
headers:
X-Request-ID: "{{ fakeit_UUID }}"
body: '{"user": "{{ fakeit_Name }}"}'
```
This validates templates.
## Show Configuration
Preview the merged configuration before running:
```sh
sarin -U http://example.com -r 1000 -c 10 \
-H "Authorization: Bearer token" \
-s
```
YAML equivalent
```yaml
url: http://example.com
requests: 1000
concurrency: 10
showConfig: true
headers:
Authorization: Bearer token
```