> For the complete documentation index, see [llms.txt](https://lab-mackleaps.gitbook.io/residencia-de-software-macklaeps-upm-fci/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://lab-mackleaps.gitbook.io/residencia-de-software-macklaeps-upm-fci/recursos-educacionais/nginx/diretivas-do-nginx.md).

# Diretivas do Nginx

De acordo com a documentação oficial, o nginx consiste em módulos controlados por diretivas especificadas nos arquivos de configuração. Elas são divididas em *diretivas simples* e *diretivas em bloco*.

Uma diretiva simples consiste no nome e nos parâmetros separados por espaços e com um ponto e vírgula (`;`) no final.

Uma diretiva de bloco permite que o desenvolvedor utilize outras diretivas dentro de chaves (`{` e `}`). Quando isso ocorre, essa diretiva de bloco é chamada de contexto (exemplos: `events`, `http`, `server` e `location`).

#### Diretiva `add_header`

A diretiva `add_header` é usada para adicionar cabeçalhos HTTP nas respostas do servidor. É muito útil para configurar cabeçalhos CORS, entre outros.

**Sintaxe:**

```nginx
add_header name value [always];
```

**Exemplo de uso:**

```nginx
location /upload {
    add_header "Access-Control-Allow-Origin" "https://*.valdeir.dev";
    add_header "Access-Control-Allow-Methods" "GET, OPTIONS";
    add_header X-Dev "Valdeir Psr" always;
}
```

#### Diretiva `alias`

A diretiva `alias` é usada para modificar a localização do diretório especificado na diretiva `root`.

**Sintaxe:**

```nginx
alias path;
```

**Exemplo de uso:**

```nginx
location /css {
    alias /dev/vda2/css/;
}
```

Este exemplo significa que a requisição para `https://valdeir.psr/css/global.css` carregará os arquivos de `/dev/vda2/css/`.

#### Diretiva `client_max_body_size`

Esta diretiva configura o tamanho máximo do corpo de uma requisição, útil para limitar o tamanho dos uploads.

**Sintaxe:**

```nginx
client_max_body_size size;
```

**Exemplo de uso:**

```nginx
client_max_body_size 1G;
```

#### Diretiva `error_page`

Permite customizar páginas de erro.

**Sintaxe:**

```nginx
error_page code ... [=[response]] uri;
```

**Exemplo de uso:**

```nginx
error_page 404 /not_found.html;
error_page 500 502 503 504 /50x.html;
error_page 401 =200 https://auth.$server_name;
```

#### Diretiva `listen`

Define o endereço e/ou porta que o Nginx deve escutar.

**Sintaxe:**

```nginx
listen address[:port] [default_server] [ssl] [http2];
listen port [default_server] [ssl] [http2];
```

**Exemplo de uso:**

```nginx
listen 80;
listen [::]:80;
listen 443 ssl;
listen [::]:443 ssl;
```

#### Diretiva `location`

Usada para aplicar configurações baseadas na URI da requisição.

**Sintaxe:**

```nginx
location [ = | ~ | ~* | ^~ ] uri { ... }
location @name { ... }
```

**Exemplo de uso:**

```nginx
location = /upload {
    # Aplica apenas se a URI for exatamente /upload
}

location ~* /upload/.*\.(jpe?g|gif|webp)$ {
    # Aplica a URIs que correspondem ao padrão regex, insensível a maiúsculas/minúsculas
}
```

#### Diretiva `map`

Cria variáveis baseadas em valores chave-valor.

**Sintaxe:**

```nginx
map $variable_nginx $variable_name { ... }
```

**Exemplo de uso:**

```nginx
map $http_user_agent $ua_blocked {
    default 0;
    ~Jorgee 1;
    ~ZmEu   1;
    ~*Spam  1;
    ~*Scan  1;
    Scanner 1;
    Wget    1;
    curl    1;
}

server {
    if ($ua_blocked) {
        return 403;
    }
}
```

Vamos expandir a documentação incluindo detalhes adicionais sobre outras diretivas importantes do Nginx que podem ser usadas para aprimorar a configuração e gestão de seu servidor web:

#### Diretiva `rewrite`

A diretiva `rewrite` é usada para reescrever URIs de requisições internamente ou para redirecionar o usuário externamente usando códigos de status 301 ou 302.

**Sintaxe:**

```nginx
rewrite regex replacement [flag];
```

**Exemplo de uso:**

```nginx
location /oldsite {
    rewrite ^(/oldsite/.*)$ /newsite/$1 permanent;
}
```

Este exemplo redireciona usuários do caminho `/oldsite` para `/newsite` usando um redirecionamento permanente (301).

#### Diretiva `proxy_pass`

A diretiva `proxy_pass` é usada para redirecionar requisições para outro servidor.

**Sintaxe:**

```nginx
proxy_pass http://backendserver_url;
```

**Exemplo de uso:**

```nginx
location /app {
    proxy_pass http://127.0.0.1:3000;
}
```

Este exemplo redireciona todas as requisições para `/app` para um servidor rodando na porta 3000 no localhost.

#### Diretiva `try_files`

A diretiva `try_files` tenta entregar o arquivo requisitado pela URI, se não encontrar, tenta a próxima opção até encontrar uma correspondência válida ou retornar um erro.

**Sintaxe:**

```nginx
try_files file1 file2 ... uri_or_error_code;
```

**Exemplo de uso:**

```nginx
location /images {
    try_files $uri $uri/ /default.png;
}
```

Esse exemplo tenta servir o arquivo solicitado em `/images`, se não existir, serve `default.png`.

#### Diretiva `gzip`

A diretiva `gzip` habilita ou desabilita a compressão gzip para respostas.

**Sintaxe:**

```nginx
gzip on|off;
```

**Exemplo de uso:**

```nginx
gzip on;
gzip_types text/plain application/xml text/css application/javascript;
gzip_vary on;
```

Este exemplo ativa a compressão gzip para tipos de conteúdo específicos e utiliza o cabeçalho `Vary` para auxiliar os proxies a gerenciar a cache corretamente.

#### Diretiva `ssl_certificate` e `ssl_certificate_key`

Essas diretivas especificam o caminho para o certificado SSL e sua chave privada, respectivamente.

**Sintaxe:**

```nginx
ssl_certificate /caminho/para/certificado.pem;
ssl_certificate_key /caminho/para/chave_privada.key;
```

**Exemplo de uso:**

```nginx
ssl_certificate /etc/nginx/ssl/meusite.pem;
ssl_certificate_key /etc/nginx/ssl/meusite.key;
```

Este exemplo configura o Nginx para usar um certificado SSL específico e sua chave.

#### server ([fonte](https://github.com/nginx/nginx/blob/41a241b3ef74dbbe3d82ab2ebbe682919e4a0b90/src/http/ngx_http_core_module.c#L2806-L2946)) <a href="#ca74" id="ca74"></a>

Essa diretiva em bloco serve para criar um servidor virtual.

```
# Syntax: server { ... }
# Default: —
# Context: http
#
server {
    server_name valdeir.dev www.valdeir.dev;
}
```

#### server\_name ([fonte](https://github.com/nginx/nginx/blob/41a241b3ef74dbbe3d82ab2ebbe682919e4a0b90/src/http/ngx_http_core_module.c#L4215-L4312)) <a href="#b762" id="b762"></a>

Define o nome/URL do servidor virtual criado. É possível definir mais de um nome quando separados por espaços. A diretiva, assim como `rewrite` e `location`, permite o uso de expressões regulares.

Criaremos abaixo um servidor virtual que receberá as requisições das URLS:

* valdeir.dev
* cdn.valdeir.dev
* assets.valdeir.dev
* qualquer-coisa.valdeir.cdn

```
server {
    # Syntax:  server_name name ...;
    # Default: server_name "";
    # Context: server
    #
    server_name valdeir.dev ~(cdn|assets)\.valdeir\.dev$ *.valdeir.cdn;
}
```

{% hint style="warning" %}
**Atenção!** Para utilizar RegExp, é necessário que o Nginx tenha sido compilado com suporte à biblioteca `PCRE`.
{% endhint %}

Através da diretiva `server_name`, você pode criar variáveis de acordo com os grupos capturados na sua expressão regular.

```
server {
    server_name ~^(www\.)?(?<domain>.+)$;

    location / {
        root /sites/$domain;
    }
}

server {
    server_name _;

    location / {
        root /sites/default;
    }
}
```

**Ordem na busca pelos servidor**

Quando há mais de um nome de servidor, o Nginx seguirá a seguinte ordem:

1. Procurar pelo nome exato (valdeir.dev);
2. Procurar pelo nome mais longo com o *wildcard* (`*`) como prefixo (\*.valdeir.dev);
3. Procurar pelo nome mais longo com o *wildcard* (`*`) como sufixo (valdeir.\*);
4. Procurar pela primeira ocorrência usando expressão regular.

#### try\_files ([fonte](https://github.com/nginx/nginx/blob/a64190933e06758d50eea926e6a55974645096fd/src/http/modules/ngx_http_try_files_module.c))

Essa diretiva verificará se um arquivo existe seguindo a ordem pré-definida pelo administrador. O processamento é feito semelhante ao das diretivas `alias` e `root`. Ela permite também que o cliente possa acessar uma pasta quando o valor terminar com uma barra (`/`). Isso é útil quando o desenvolvedor utiliza a diretiva `autoindex`. Se arquivo nenhum for encontrado, o o usuário será redirecionado para outra página, URL ou bloco `location` nomeado.

```
root /var/www/html;

autoindex on;

location /upload {
    # Syntax: try_files file ... uri;
    #         try_files file ... =code;
    # Default: —
    # Context: server, location
    #
    try_files $uri $uri/ /empty.gif =444;
}
```

No exemplo acima, ao acessar a requisição `/upload/avatar.webp`, o Nginx seguirá a seguinte ordem:

1. Verifica se o arquivo `/var/www/html/upload/avatar.webp` existe; se não existir,
2. Verifica se a pasta `/var/www/html/upload/avatar.webp/` existe; se não existir,
3. Verifica se o arquivo `/var/www/html/empty.gif` existe; se não existir,
4. Fecha a conexão sem uma resposta (usando o `=444`).

É possível também utilizar bloco `location` nomeado.

```
location / {
  try_files $uri $uri/ @opencart;
}

location @opencart {
  rewrite ^/sitemap.xml$ /index.php?route=extension/feed/google_sitemap last;
  rewrite ^/googlebase.xml$ /index.php?route=extension/feed/google_base last;
  rewrite ^/system/storage/(.*) /index.php?route=error/not_found last;

  rewrite ^/(.+)$ /index.php?_route_=$1 last;
}

location ~* (\.twig|\.tpl|\.ini|\.log|(?<!robots)\.txt)$ {
  deny all;
}
```

**Mais Informações:**

{% embed url="<https://medium.com/@valdeirpsr/s%C3%A9rie-nginx-3-conhe%C3%A7a-as-diretivas-do-nginx-1abebd4b3da>" %}

<br>