<!-- review: finished -->

<a id="http-upstream"></a>

# Upstream

Fornece um contexto para descrever grupos de servidores que podem ser usados nas diretivas [proxy_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-pass), [fastcgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-pass), [uwsgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-pass), [scgi_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-pass), [memcached_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-pass) e [grpc_pass](https://pt.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-pass).

<a id="configuration-example-45"></a>

## Exemplo de Configuração

```nginx
upstream backend {
    zone backend 1m;
    server backend1.example.com       weight=5;
    server backend2.example.com:8080;
    server backend3.example.com       service=_example._tcp resolve;
    server unix:/tmp/backend3;

    server backup1.example.com:8080   backup;
    server backup2.example.com:8080   backup;
}

resolver 127.0.0.53 status_zone=resolver;

server {
    location / {
        proxy_pass http://backend;
    }
}
```

<a id="directives-48"></a>

## Diretivas

<a id="index-0"></a>

<a id="u-backup-switch"></a>

### backup_switch (PRO)

#### Versionadded
Adicionado na versão 1.9.0: PRO

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `backup_switch` `permanent`[=time];   |
|-------------------------------------------------------------------------------------------|---------------------------------------|
| Padrão                                                                                    | —                                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                              |

A diretiva habilita a capacidade de iniciar a seleção de servidor não a partir do grupo primário,
mas a partir do grupo *ativo*, ou seja, aquele onde um servidor foi encontrado com sucesso na última vez.
Se um servidor não puder ser encontrado no grupo ativo para a próxima requisição,
e a busca se mover para o grupo de backup,
então este grupo se torna ativo,
e as requisições subsequentes são direcionadas primeiro para servidores neste grupo.

Se o parâmetro `permanent` for definido sem um valor de [time](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax),
o grupo permanece ativo após a seleção,
e a reverificação automática de grupos com níveis mais baixos não ocorre.
Se time for especificado,
o status ativo do grupo expira após o intervalo especificado,
e o balanceador verifica novamente grupos com níveis mais baixos,
retornando a eles se os servidores estiverem funcionando normalmente.

Exemplo:

```nginx
upstream my_backend {
    server primary1.example.com;
    server primary2.example.com;

    server backup1.example.com backup;
    server backup2.example.com backup;

    backup_switch permanent=2m;
}
```

Se o balanceador alternar dos servidores primários para o grupo de backup,
todas as requisições subsequentes são tratadas por este grupo de backup por 2 minutos.
Após 2 minutos decorrerem, o balanceador verifica novamente os servidores primários
e os torna ativos novamente se estiverem funcionando normalmente.

<a id="index-1"></a>

<a id="u-bind-conn"></a>

### bind_conn (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `bind_conn` value;   |
|-------------------------------------------------------------------------------------------|----------------------|
| Padrão                                                                                    | —                    |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream             |

Permite vincular uma conexão do servidor a uma conexão do cliente quando o
value, especificado como uma string de variáveis, se torna diferente de `""` e
`"0"`.

#### WARNING
A diretiva `bind_conn` deve ser usada após todas as diretivas
que definem um método de balanceamento de carga,
caso contrário não funcionará.
Se for usada junto com a diretiva [sticky](#u-sticky),
então `bind_conn` deve vir após `sticky`.

#### WARNING
Ao usar a diretiva, as configurações do módulo [Proxy](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#http-proxy)
devem permitir o uso de conexões persistentes, por exemplo:

```nginx
proxy_http_version 1.1;
proxy_set_header Connection "";
```

Um caso de uso típico para a diretiva é fazer proxy de conexões com
autenticação NTLM, onde é necessário garantir a vinculação cliente-servidor no
início da negociação:

```nginx
map $http_authorization   $ntlm {
    ~*^N(?:TLM|egotiate)  1;
}

upstream ntlm_backend {
    server 127.0.0.1:8080;
    bind_conn $ntlm;
}

server {
    # ...
    location / {
        proxy_pass http://ntlm_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        # ...
    }
}
```

<a id="index-2"></a>

<a id="u-feedback"></a>

### feedback (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `feedback` variable [`inverse`] [`factor=`number] [`account=`condition_variable] [`last_byte`];   |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                                 |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                          |

Configura um mecanismo de balanceamento de carga baseado em feedback no `upstream`.
Ele ajusta dinamicamente as decisões de balanceamento
multiplicando o peso de cada servidor proxy pelo valor médio de feedback,
que muda ao longo do tempo dependendo do valor da variable
e está sujeito a uma condição opcional.

Os seguintes parâmetros podem ser especificados:

| `variable`   | A variável da qual o valor de feedback é obtido.<br/>Ela deve representar uma métrica de desempenho ou saúde;<br/>assume-se que o servidor a forneça em cabeçalhos ou de outra forma.<br/><br/>O valor é avaliado com cada resposta do servidor<br/>e é considerado na média móvel<br/>de acordo com as configurações `inverse` e `factor`.                                                                                                                                                                                                                                                                                                                                                                                     |
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `inverse`    | Se o parâmetro for definido, o valor de feedback é interpretado inversamente:<br/>valores menores indicam melhor desempenho.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `factor`     | O fator pelo qual o valor de feedback é considerado<br/>ao calcular a média.<br/>Valores válidos são inteiros de 0 a 99.<br/>O padrão é `90`.<br/><br/>A média é calculada usando a fórmula de [suavização exponencial](https://en.wikipedia.org/wiki/Exponential_smoothing).<br/><br/>Quanto maior o fator, menos os novos valores afetam a média;<br/>se `90` for especificado, então 90% do valor anterior<br/>e apenas 10% do novo valor serão considerados.                                                                                                                                                                                                                                                                |
| `account`    | Especifica uma variável de condição<br/>que controla quais respostas são consideradas no cálculo.<br/>O valor médio é atualizado com o valor de feedback da resposta<br/>apenas se a variável de condição dessa resposta<br/>não for igual a `""` ou `"0"`.<br/><br/>#### NOTE<br/>Por padrão, respostas durante [verificações ativas](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)<br/>não são incluídas no cálculo;<br/>combinar a variável [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>com `account` permite incluir essas respostas<br/>ou até mesmo excluir todo o resto. |
| `last_byte`  | Permite processar dados do servidor proxy após receber<br/>a resposta completa, não apenas o cabeçalho.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

Exemplo:

```nginx
upstream backend {

    zone backend 1m;

    feedback $feedback_value factor=80 account=$condition_value;

    server backend1.example.com;
    server backend2.example.com;
}

map $upstream_http_custom_score $feedback_value {
    "high"                      100;
    "medium"                    75;
    "low"                       50;
    default                     10;
}

map $upstream_probe $condition_value {
    "high_priority" "1";
    "low_priority"  "0";
    default         "1";
}
```

Esta configuração categoriza respostas do servidor por níveis de feedback
baseados em pontuações específicas dos campos de cabeçalho de resposta,
e também adiciona uma condição em [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)
para considerar apenas respostas da verificação ativa `high_priority`
ou respostas a requisições regulares de clientes.

<a id="index-3"></a>

<a id="u-hash"></a>

### hash

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `hash` key [`consistent`];   |
|-------------------------------------------------------------------------------------------|------------------------------|
| Padrão                                                                                    | —                            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                     |

Especifica um método de balanceamento de carga para um grupo de servidores onde o mapeamento cliente-servidor é determinado usando o valor da chave hash. A chave pode conter texto, variáveis e suas combinações. Note que adicionar ou remover um servidor do grupo pode resultar no remapeamento da maioria das chaves para servidores diferentes. O método é compatível com a biblioteca Perl [Cache::Memcached](https://metacpan.org/pod/Cache::Memcached).

```nginx
hash $remote_addr;
```

Ao usar nomes de domínio que resolvem para múltiplos endereços IP
(por exemplo, com o parâmetro `resolve`),
o servidor não ordena os endereços recebidos, então sua ordem pode diferir
entre diferentes servidores, o que afeta a distribuição de clientes.
Para garantir distribuição consistente,
use o parâmetro `consistent`.

Se o parâmetro `consistent` for especificado, o método de hash consistente [ketama](https://www.metabrew.com/article/libketama-consistent-hashing-algo-memcached-clients) será usado. O método garante que apenas algumas chaves serão remapeadas para servidores diferentes quando um servidor for adicionado ou removido do grupo. Isso ajuda a alcançar uma taxa de acerto de cache mais alta para servidores de cache. O método é compatível com a biblioteca Perl [Cache::Memcached::Fast](https://metacpan.org/pod/Cache::Memcached::Fast) com o parâmetro `ketama_points` definido como 160.

<a id="index-4"></a>

<a id="u-ip-hash"></a>

### ip_hash

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `ip_hash`;   |
|-------------------------------------------------------------------------------------------|--------------|
| Padrão                                                                                    | —            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream     |

Especifica um método de balanceamento de carga para o grupo onde as requisições são distribuídas entre servidores com base nos endereços IP dos clientes. Os primeiros três octetos do endereço IPv4 do cliente ou todo o endereço IPv6 são usados como chave de hash. O método garante que requisições do mesmo cliente sempre sejam passadas para o mesmo servidor, exceto quando este servidor estiver indisponível. Neste caso, as requisições do cliente serão passadas para outro servidor. Muito provavelmente este também será o mesmo servidor.

Se um dos servidores precisar ser temporariamente removido, ele deve ser marcado com o parâmetro `down` para preservar o hash atual dos endereços IP dos clientes:

```nginx
upstream backend {
    ip_hash;

    server backend1.example.com;
    server backend2.example.com;
    server backend3.example.com down;
    server backend4.example.com;
}
```

<a id="index-5"></a>

<a id="u-keepalive"></a>

### keepalive

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive` connections;   |
|-------------------------------------------------------------------------------------------|----------------------------|
| Padrão                                                                                    | —                          |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                   |

Ativa o cache de conexões para servidores upstream.

O parâmetro `connections` define o número máximo de conexões keepalive ociosas para servidores upstream que são preservadas no cache de cada processo worker. Quando este número é excedido, as conexões menos recentemente usadas são fechadas.

#### NOTE
Deve ser particularmente notado que a diretiva `keepalive` não limita o número total de conexões para servidores upstream que os processos worker do Angie podem abrir. O parâmetro `connections` deve ser definido baixo o suficiente para permitir que os servidores upstream processem novas conexões de entrada também.

#### WARNING
A diretiva `keepalive` deve ser usada após todas as diretivas que definem
um método de balanceamento de carga; caso contrário, não funcionará.

Exemplo de configuração de upstream memcached com conexões keepalive:

```nginx
upstream memcached_backend {
    server 127.0.0.1:11211;
    server 10.0.0.2:11211;

    keepalive 32;
}

server {
    #...

    location /memcached/ {
        set $memcached_key $uri;
        memcached_pass memcached_backend;
    }

}
```

Para HTTP, a diretiva [proxy_http_version](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-http-version) deve ser definida como "1.1" e o campo de cabeçalho `Connection` deve ser limpo:

```nginx
upstream http_backend {
    server 127.0.0.1:8080;

    keepalive 16;
}

server {
    #...

    location /http/ {
        proxy_pass http://http_backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    #    ...
    }
}
```

#### NOTE
Alternativamente, conexões persistentes HTTP/1.0 podem ser usadas passando o campo de cabeçalho "Connection: Keep-Alive" para um servidor upstream, embora este método não seja recomendado.

Para servidores FastCGI, é necessário definir [fastcgi_keep_conn](https://pt.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-keep-conn) para que as conexões keepalive funcionem:

```nginx
upstream fastcgi_backend {
    server 127.0.0.1:9000;

    keepalive 8;
}

server {
    #...

    location /fastcgi/ {
        fastcgi_pass fastcgi_backend;
        fastcgi_keep_conn on;
    #    ...
    }
}
```

#### NOTE
Os protocolos SCGI e uwsgi não têm um conceito de conexões keepalive.

<a id="index-6"></a>

<a id="u-keepalive-requests"></a>

### keepalive_requests

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_requests` number;   |
|-------------------------------------------------------------------------------------------|--------------------------------|
| Padrão                                                                                    | `keepalive_requests 1000;`     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                       |

Define o número máximo de requisições que podem ser atendidas através de uma conexão keepalive. Após o número máximo de requisições ser feito, a conexão é fechada.

Fechar conexões periodicamente é necessário para liberar alocações de memória por conexão. Portanto, usar um número máximo de requisições muito alto pode resultar em uso excessivo de memória e não é recomendado.

<a id="index-7"></a>

<a id="u-keepalive-time"></a>

### keepalive_time

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_time` time;   |
|-------------------------------------------------------------------------------------------|--------------------------|
| Padrão                                                                                    | `keepalive_time 1h;`     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                 |

Limita o tempo máximo durante o qual requisições podem ser processadas através de uma conexão keepalive. Após este tempo ser alcançado, a conexão é fechada após o processamento da requisição subsequente.

<a id="index-8"></a>

<a id="u-keepalive-timeout"></a>

### keepalive_timeout

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `keepalive_timeout` timeout;   |
|-------------------------------------------------------------------------------------------|--------------------------------|
| Padrão                                                                                    | `keepalive_timeout 60s;`       |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                       |

Define um timeout durante o qual uma conexão keepalive ociosa para um servidor upstream permanecerá aberta.

<a id="index-9"></a>

<a id="u-least-conn"></a>

### least_conn

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_conn`;   |
|-------------------------------------------------------------------------------------------|-----------------|
| Padrão                                                                                    | —               |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Especifica que um grupo deve usar um método de balanceamento de carga onde uma requisição é passada para o servidor com o menor número de conexões ativas, levando em conta os pesos dos servidores. Se houver vários servidores assim, eles são tentados alternadamente usando um método de balanceamento round-robin ponderado.

<a id="index-10"></a>

<a id="u-least-time"></a>

### least_time (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `least_time` `header` | `last_byte` [`factor=`number] [`account=`condition_variable];   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                       |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                |

Especifica que o grupo deve usar um método de balanceamento de carga onde a chance de um servidor ativo receber a requisição é inversamente proporcional ao seu tempo médio de resposta; quanto menor for, mais requisições um servidor recebe.

| `header`    | A diretiva considera o tempo médio para receber cabeçalhos de resposta.   |
|-------------|---------------------------------------------------------------------------|
| `last_byte` | A diretiva usa o tempo médio para receber toda a resposta.                |

| `factor`   | Serve ao mesmo propósito que [response_time_factor (PRO)](#u-response-time-factor)<br/>e o substitui se o parâmetro for definido.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `account`  | Especifica uma variável de condição<br/>que controla quais respostas são incluídas no cálculo.<br/>A média é atualizada<br/>apenas se a variável de condição para a resposta<br/>não for `""` ou `"0"`.<br/><br/>#### NOTE<br/>Por padrão, respostas durante [sondagens de saúde ativas](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe)<br/>não são incluídas no cálculo;<br/>combinar a variável [$upstream_probe](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#v-upstream-probe)<br/>com `account` permite incluir essas respostas<br/>ou até mesmo excluir todo o resto. |

Os valores atuais são apresentados como `header_time` (apenas cabeçalhos)
e `response_time` (respostas completas) no objeto `health` do servidor
entre as [métricas upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) na API.

<a id="index-11"></a>

<a id="u-queue"></a>

### queue (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `queue` number [`timeout=`time];   |
|-------------------------------------------------------------------------------------------|------------------------------------|
| Padrão                                                                                    | —                                  |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                           |

Se não for possível atribuir um servidor proxy a uma requisição na primeira tentativa
(por exemplo, durante uma breve interrupção de serviço
ou quando há um pico de carga atingindo o limite [max_conns](#u-server)),
a requisição não é rejeitada;
em vez disso, o Angie tenta enfileirá-la para processamento.

O parâmetro number da diretiva define o número máximo de requisições
na fila para um [processo worker](https://pt.angie.software//angie/docs/configuration/modules/core.md#worker-processes).
Se a fila estiver cheia,
um erro `502 (Bad Gateway)` é retornado ao cliente.

#### NOTE
A lógica da diretiva [proxy_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream) também se aplica a requisições enfileiradas.
Especificamente, se um servidor foi selecionado para uma requisição
mas ela não pode ser entregue a ele,
a requisição pode ser retornada à fila.

Se um servidor não for selecionado para processar uma requisição enfileirada
dentro do [tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax) definido por `timeout`
(padrão é 60 segundos),
um erro `502 (Bad Gateway)` é retornado ao cliente.
Requisições de clientes que fecham prematuramente a conexão também são removidas da fila;
há contadores para os estados de requisições passando pela fila na [API](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#a-queue).

#### WARNING
A diretiva `queue` deve ser usada após todas as diretivas que definem o
método de balanceamento de carga; caso contrário, não funcionará.

<a id="index-12"></a>

<a id="u-random"></a>

### random

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `random` [`two`];   |
|-------------------------------------------------------------------------------------------|---------------------|
| Padrão                                                                                    | —                   |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream            |

Especifica um método de balanceamento de carga para o grupo onde uma requisição é passada para um servidor selecionado aleatoriamente, levando em conta os pesos dos servidores.

Se o parâmetro opcional `two` for especificado, o Angie seleciona aleatoriamente dois servidores, então seleciona um deles usando o método [least_conn](#u-least-conn), onde uma requisição é passada para o servidor com o menor número de conexões ativas.

<a id="index-13"></a>

<a id="u-response-time-factor"></a>

### response_time_factor (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `response_time_factor` number;   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | `response_time_factor 90;`       |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Define o fator de suavização para o valor **anterior** ao calcular o tempo médio de resposta para o método de balanceamento de carga [least_time (PRO)](#u-least-time) usando a fórmula de [média móvel exponencialmente ponderada](https://en.wikipedia.org/wiki/Moving_average#Exponential_moving_average).

Quanto maior o number especificado, menos os novos valores afetam a média; se
`90` for especificado, 90% do valor anterior e apenas 10% do
novo valor serão considerados. Os valores válidos variam de 0 a 99, inclusive.

Os resultados atuais do cálculo são apresentados como `header_time`
(apenas cabeçalhos) e `response_time` (respostas completas) no objeto `health`
do servidor entre as [métricas upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-status-http-upstreams) na API.

#### NOTE
Apenas respostas bem-sucedidas são incluídas no cálculo; o que é considerado uma resposta
mal-sucedida é determinado pelas diretivas [proxy_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream), e
[grpc_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream). Além disso, o valor `header_time`
é recalculado apenas se todos os cabeçalhos forem recebidos e processados, e
`response_time` — apenas se toda a resposta for recebida.

<a id="index-14"></a>

<a id="u-server"></a>

### server

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `server` address [parameters];   |
|-------------------------------------------------------------------------------------------|----------------------------------|
| Padrão                                                                                    | —                                |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                         |

Define o endereço e outros parâmetros de um servidor. O endereço pode ser especificado como um nome de domínio ou endereço IP, com uma porta opcional, ou como um caminho de socket de domínio UNIX especificado após o prefixo `unix:`. Se uma porta não for especificada, a porta 80 é usada. Um nome de domínio que resolve para vários endereços IP define múltiplos servidores de uma vez.

Os seguintes parâmetros podem ser definidos:

| `weight=`number    | Define o peso do servidor. O padrão é 1.                                                                                                                                                                                                             |
|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max_conns=`number | Limita o número máximo de conexões ativas simultâneas para o servidor com proxy. O valor padrão é `0`, significando que não há limite. Se o grupo não residir na [zona de memória compartilhada](#u-zone), a limitação funciona por processo worker. |

#### NOTE
Com as [conexões keepalive inativas](#u-keepalive) habilitadas, múltiplos [processos worker](https://pt.angie.software//angie/docs/configuration/modules/core.md#worker-processes), e uma [zona de memória compartilhada](#u-zone), o número total de conexões ativas e inativas para o servidor com proxy pode exceder o valor `max_conns`.

<a id="max-fails"></a>

`max_fails=`number — define o número de tentativas malsucedidas
de comunicação com o servidor
que devem ocorrer durante o período especificado por [fail_timeout](#fail-timeout)
para que o servidor seja considerado indisponível;
após isso, ele será verificado novamente após o mesmo período.

O que é considerado uma
tentativa malsucedida é definido pelas diretivas [proxy_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-next-upstream),
[fastcgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_fastcgi.md#fastcgi-next-upstream), [uwsgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_uwsgi.md#uwsgi-next-upstream),
[scgi_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_scgi.md#scgi-next-upstream), [memcached_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_memcached.md#memcached-next-upstream), e
[grpc_next_upstream](https://pt.angie.software//angie/docs/configuration/modules/http/http_grpc.md#grpc-next-upstream).

Quando `max_fails` é excedido, o servidor também é considerado indisponível da perspectiva das
[upstream_probe (PRO)](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe); requisições de clientes não serão direcionadas a ele
até que as verificações determinem que ele está disponível.

#### NOTE
Se uma diretiva `server` em um grupo resolve em múltiplos servidores,
sua configuração `max_fails` se aplica a cada servidor separadamente.

Se após resolver todas as diretivas `server`
apenas um servidor permanecer no upstream,
a configuração `max_fails` não tem efeito e será ignorada.

| `max_fails=1`   | Número padrão de tentativas;               |
|-----------------|--------------------------------------------|
| `max_fails=0`   | Desabilita a contabilização de tentativas. |

<a id="fail-timeout"></a>

`fail_timeout=`time — define o período de tempo durante o qual
um número especificado de tentativas malsucedidas de comunicação com o servidor
([max_fails](#max-fails)) deve ocorrer para que o servidor seja considerado indisponível.
O servidor então permanece indisponível pelo mesmo período de tempo
antes de ser verificado novamente.

O valor padrão é 10 segundos.

#### NOTE
Se uma diretiva `server` em um grupo resolve em múltiplos servidores,
sua configuração `fail_timeout` se aplica a cada servidor separadamente.

Se após resolver todas as diretivas `server`
apenas um servidor permanecer no upstream,
a configuração `fail_timeout` não tem efeito e será ignorada.

| `backup`      | Marca o servidor como um servidor de backup. Ele receberá requisições quando os servidores primários estiverem indisponíveis.<br/><br/>Se a diretiva [backup_switch (PRO)](#u-backup-switch) estiver especificada,<br/>sua lógica de backup ativo também se aplica.   |
|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `down`        | Marca o servidor como permanentemente indisponível.                                                                                                                                                                                                                   |
| `drain` (PRO) | Marca o servidor como em drenagem; isso significa<br/>que ele recebe apenas requisições de sessões<br/>vinculadas anteriormente via [sticky](#u-sticky).<br/>Caso contrário, o comportamento é o mesmo do modo `down`.                                                |

#### WARNING
O parâmetro `backup` não pode ser usado junto com os métodos de
balanceamento de carga [hash](#u-hash), [ip_hash](#u-ip-hash),
e [random](#u-random).

Os parâmetros `down` e `drain` são mutuamente exclusivos.

<a id="reresolve"></a>

| `resolve`      | Permite monitorar mudanças na lista de endereços IP correspondentes a<br/>um nome de domínio e atualizá-la sem recarregar a configuração.<br/>O grupo deve residir em<br/>[memória compartilhada](#u-zone);<br/>um [resolver](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#resolver) também deve ser definido.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `service=`name | Habilita a resolução de registros DNS SRV e define o nome do serviço. Para<br/>que o parâmetro funcione, o parâmetro `resolve` deve ser especificado para o servidor,<br/>sem especificar uma porta no hostname.<br/><br/>Se o nome do serviço não contiver um ponto, um nome é formado de acordo com o padrão RFC:<br/>o nome do serviço é prefixado com `_`,<br/>então `_tcp` é adicionado após um ponto.<br/>Assim, o nome do serviço `http` resulta em `_http._tcp`.<br/><br/>O Angie resolve registros SRV<br/>combinando o nome do serviço normalizado e o hostname<br/>e obtendo uma lista de servidores para a combinação resultante via DNS,<br/>junto com suas prioridades e pesos.<br/><br/>- Registros SRV com a prioridade mais alta<br/>  (aqueles com o menor valor de prioridade)<br/>  são resolvidos como servidores primários,<br/>  enquanto outros registros se tornam servidores de backup.<br/>  Se `backup` estiver definido com `server`,<br/>  registros SRV com a prioridade mais alta são resolvidos como servidores de backup,<br/>  e outros registros são ignorados.<br/>- Peso é análogo ao parâmetro `weight` da diretiva `server`.<br/>  Se o peso for especificado tanto na diretiva quanto no registro SRV,<br/>  o peso definido na diretiva é usado. |

Neste exemplo, uma busca é realizada pelo registro `_http._tcp.backend.example.com`:

```nginx
server backend.example.com service=http resolve;
```

| `sid=`id   | Define o ID do servidor no grupo. Se o parâmetro não for especificado,<br/>o ID é definido como um hash MD5 hexadecimal<br/>do endereço IP e porta ou caminho do socket UNIX.   |
|------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

<a id="slow-start"></a>

| `slow_start=`time   | Define o [tempo](https://pt.angie.software//angie/docs/configuration/configfile.md#syntax) para recuperação gradual do peso de um servidor que retorna<br/>ao balanceamento de carga com o<br/>método [round-robin](#round-robin) ou [least_conn](#u-least-conn).<br/><br/>Se o parâmetro for definido<br/>e o servidor for considerado operacional novamente após uma falha<br/>da perspectiva de [max_fails](#max-fails) e [upstream_probe (PRO)](https://pt.angie.software//angie/docs/configuration/modules/http/http_upstream_probe.md#u-upstream-probe),<br/>tal servidor aumenta gradualmente para seu peso especificado<br/>durante o período de tempo determinado.<br/><br/>Se o parâmetro não for definido,<br/>em uma situação similar<br/>o servidor imediatamente começa a operar com seu peso especificado.   |
|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

#### NOTE
Se apenas um `server` for especificado no upstream,
`slow_start` não funciona e será ignorado.

<a id="index-15"></a>

<a id="u-state"></a>

### state (PRO)

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `state` file;   |
|-------------------------------------------------------------------------------------------|-----------------|
| Padrão                                                                                    | —               |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream        |

Especifica um file onde a lista de servidores upstream é armazenada persistentemente.
Ao instalar a partir dos
[nossos pacotes](https://pt.angie.software//angie/docs/installation/index.md#install-packages),
o diretório
`/var/lib/angie/state/` (`/var/db/angie/state/` no FreeBSD)
é criado especificamente para armazenar tais arquivos
com permissões de acesso apropriadas,
e na configuração você só precisa adicionar o nome do arquivo:

```nginx
upstream backend {

    zone backend 1m;
    state /var/lib/angie/state/<FILE NAME>;
}
```

A lista de servidores aqui tem um formato similar ao `server`.
O conteúdo do arquivo é modificado sempre que servidores são alterados na
seção [/config/http/upstreams/](https://pt.angie.software//angie/docs/configuration/modules/http/http_api.md#api-config-http-upstreams-servers)
via API de configuração.
O arquivo é lido quando o Angie inicia ou quando a configuração é recarregada.

#### WARNING
Para usar a diretiva `state` em um bloco `upstream`,
não deve haver diretivas `server` nele,
mas uma zona de memória compartilhada ([zone](#u-zone)) é necessária.

<a id="index-16"></a>

<a id="u-sticky"></a>

### sticky

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky` cookie name [attr=value]...;<br/><br/>`sticky route` value...;<br/><br/>`sticky learn` `zone=`zone `create=`$create_var1... `lookup=`$lookup_var1... [`header`] [`norefresh`] [`timeout=`time];<br/><br/>`sticky learn` [`zone=`zone] `lookup=`$lookup_var1... `remote_action=`uri `remote_result=`$remote_var [`norefresh`] [`timeout=`time];   |
|-------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Padrão                                                                                    | —                                                                                                                                                                                                                                                                                                                                                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                                                                                                                                                                                                                                                                                                                                                  |

Configura afinidade de sessão para vincular sessões de cliente a servidores proxy
no modo especificado pelo primeiro parâmetro;
para drenar servidores
que têm a diretiva `sticky` configurada,
você pode usar a opção `drain` (PRO)
no bloco [server](#u-server).

#### WARNING
A diretiva `sticky` deve ser usada após todas as diretivas
que especificam um método particular de balanceamento de carga,
caso contrário não funcionará.
Se for usada junto com a diretiva [bind_conn (PRO)](#u-bind-conn),
então `bind_conn` deve vir após `sticky`.

modo `cookie`

Este modo usa cookies para gerenciar sessões.
É adequado quando cookies já são usados para rastreamento de sessão.

A primeira requisição do cliente, antes de qualquer aderência se aplicar,
é enviada para um servidor backend de acordo com o método de balanceamento configurado.
O Angie então define um cookie identificando o servidor escolhido.

O nome do cookie (`name`) é definido pela diretiva `sticky`,
e seu valor corresponde ao [sid](#reresolve)
da diretiva [server](#u-server).
Este valor é posteriormente hasheado se [sticky_secret](#u-sticky-secret) estiver definido.

Requisições subsequentes com este cookie são roteadas para o servidor
especificado por seu [sid](#reresolve).
Se o servidor estiver indisponível ou não puder processar a requisição,
outro é escolhido através do método de balanceamento configurado.

Você pode atribuir atributos de cookie na diretiva;
por padrão, apenas `path=/` é definido.
Valores de atributos podem conter variáveis.
Para remover um atributo, defina-o como um valor vazio: `attr=`.
Por exemplo, `sticky cookie path=` omite o atributo `path`.

Este exemplo define um cookie `srv_id` por 1 hora,
usando um domínio de uma variável:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie srv_id domain=$my_domain max-age=3600;
}
```

modo `route`

Este modo usa identificadores de rota predefinidos,
que podem vir de URLs, cookies ou argumentos de requisição.
É menos flexível, mas bom quando tais identificadores já existem.

O servidor backend pode retornar um ID de rota conhecido tanto pelo cliente quanto pelo servidor.
Este valor deve corresponder ao [sid](#reresolve).

Requisições subsequentes devem carregar o ID da rota,
por exemplo, através de um [cookie](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-cookie) ou [argumento de consulta](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#v-arg).

A diretiva recebe uma lista de strings que podem incluir variáveis
para extrair o ID da rota. O primeiro resultado não vazio é comparado com
[sid](#reresolve).

Neste exemplo, o Angie verifica primeiro o cookie `route`,
depois o argumento de consulta `route`:

```nginx
upstream backend {
    server backend1.example.com:8080 "sid=server 1";
    server backend2.example.com:8080 "sid=server 2";

    sticky route $cookie_route $arg_route;
}
```

modo `learn` (PRO 1.4.0+)

Este modo usa uma chave gerada dinamicamente para atribuir um cliente a um backend.
É flexível e suporta armazenamento de sessão em memória compartilhada
e várias fontes de identificador.

Uma sessão é criada a partir da resposta do servidor backend.
`create` e `lookup` definem como gerar e localizar sessões,
e ambos aceitam múltiplas variáveis.

O ID da sessão é a primeira variável não vazia de `create`.
Por exemplo, pode vir de um cookie de resposta.

Sessões são armazenadas em memória compartilhada,
definida com `zone name:size`.
Se não usada por duração `timeout` (padrão: 1 hora), a sessão expira.

Por padrão, o Angie atualiza sessões a cada uso.
Para desabilitar isso, use `norefresh`.

O ID da sessão de uma requisição do cliente é extraído via `lookup`,
usando a primeira variável não vazia listada.
Se nenhuma for encontrada, é uma nova requisição.

Use `header` para criar a sessão ao receber cabeçalhos de resposta
em vez de após o processamento completo da resposta.

Exemplo: sessão criada usando `examplecookie`:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky learn
        create=$upstream_cookie_examplecookie
        lookup=$cookie_examplecookie
        zone=client_sessions:1m;
}
```

`learn` com `remote_action` (PRO 1.8.0+)

Use `remote_action` e `remote_result`
para gerenciar IDs de sessão com um armazenamento de sessão externo.
A zona de memória compartilhada atua como cache;
o armazenamento externo é autoritativo.
`create` não é compatível com `remote_action`.

Sessões expiram após `timeout` (padrão: 1 hora),
independentemente de `remote_action`.

Por padrão, o Angie atualiza o TTL da sessão a cada uso.
Use `norefresh` para desabilitar isso.

`zone` é opcional com `remote_action`.
Sem ela, o Angie sempre consulta o armazenamento externo.

Fluxo básico:

- Extrair ID da sessão da primeira variável `lookup` não vazia.
  Se nenhuma, recorrer ao balanceamento de carga padrão.
- Se `zone` estiver definida e a sessão existir, usá-la e parar.
- Se não houver sessão ou zona, escolher um servidor e fazer uma subrequisição HTTP
  para o endpoint `remote_action` com:
  - ID da sessão ([$sticky_sessid](#v-sticky-sessid));
  - ID do servidor de `sid=` ou de [$sticky_sid](#v-sticky-sid).

  Enviar estes como cabeçalhos HTTP (via [proxy_set_header](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-set-header)).
- O armazenamento remoto responde:
  - 200/201/204 confirma a sessão; armazená-la em cache se `zone` estiver definida.
  - 409 sinaliza conflito (se `zone` estiver definida) — sessão vinculada a outro servidor.
    Usar `remote_result` para extrair o ID do servidor corrigido.
  - Outros códigos de status ou ID de servidor ausente — recorrer ao servidor original.

`remote_result` usa variáveis `upstream_http_*`
para ler cabeçalhos da resposta do armazenamento remoto.

Exemplo: ID da sessão vem de `$cookie_bar`,
confirmado via `$upstream_http_x_sticky_sid`:

```nginx
http {

    upstream u1 {
        server srv1;
        server srv2;

        sticky learn zone=sz:1m
            lookup=$cookie_bar
            remote_action=/remote_session
            remote_result=$upstream_http_x_sticky_sid;

        zone z 1m;
    }

    server {

        listen localhost;

        location / {
            proxy_pass http://u1/;
        }

        location /remote_session {
            internal;
            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid $sticky_sid;
            proxy_set_header X-Sticky-Last $msec;
            proxy_pass http://remote;
        }
    }
}
```

The following is a simplified configuration example.
The remote store returns the session ID in the `X-Sid` header
and so confirms or overrides Angie's choice:

```nginx
http {

    proxy_cache_path c1 keys_zone=s1:1m;

    upstream tc_0 {
        server 10.0.0.1 sid=web-server-01;
        server 10.0.0.2 sid=web-server-02;

        sticky learn
            lookup=$arg_id
            remote_action=@create_session
            remote_result=$upstream_http_x_sid;
    }

    server {
        listen 127.0.0.1:8080;

        location / {
            proxy_pass http://tc_0/;
        }

        # Request to the remote session store
        location @create_session {
            internal;

            proxy_set_header X-Sticky-Sessid $sticky_sessid;
            proxy_set_header X-Sticky-Sid    $sticky_sid;
            proxy_set_header X-Sticky-Last   $msec;

            proxy_pass http://session_backend;

            proxy_connect_timeout 1s;
            proxy_read_timeout    1s;

            proxy_cache        s1;
            proxy_cache_valid  200 1d;
            proxy_cache_key    "$scheme$proxy_host$request_uri$sticky_sessid";
        }
    }
}
```

Exemplo de resposta:

```none
HTTP/1.1 200 OK
...
X-Sid: web-server-01
X-Session-Backend: backend-pool-1
```

Variáveis do Angie resultantes:

- `$upstream_http_x_sid` → `web-server-01`
- `$upstream_http_x_session_backend` → `backend-pool-1`

`remote_result` usará `web-server-01`
para selecionar o `sid` correspondente.

A diretiva `sticky` respeita os estados dos servidores upstream:

- Servidores marcados como `down` ou falhando são excluídos.
- Servidores acima do limite `max_conns` são ignorados.
- Servidores `drain` (PRO) ainda podem ser selecionados para novas sessões no modo `sticky` quando os identificadores correspondem.
- Servidores recuperados são reutilizados automaticamente.

Você pode ajustar ainda mais o comportamento usando
[sticky_secret](#u-sticky-secret) e [sticky_strict](#u-sticky-strict).
Se a aderência falhar e `sticky_strict` estiver desligado,
o balanceamento de fallback é usado;
se ligado, a requisição é rejeitada.

Cada `zone` usada em `sticky` deve ser exclusiva de um único `upstream`.
Zonas não podem ser compartilhadas entre múltiplos blocos `upstream`.

<a id="index-17"></a>

<a id="u-sticky-secret"></a>

### sticky_secret

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_secret` string;   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | —                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                  |

Adiciona a string como valor de salt para a função de hash MD5
da diretiva [sticky](#u-sticky) nos modos `cookie` e `route`.
A string pode conter variáveis, por exemplo, `$remote_addr`:

```nginx
upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}
```

O salt é anexado ao valor sendo hasheado;
para verificar o mecanismo de hash independentemente:

```console
$ echo -n "<VALUE><SALT>" | md5sum
```

<a id="index-18"></a>

<a id="u-sticky-strict"></a>

### sticky_strict

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `sticky_strict` `on` | `off`;   |
|-------------------------------------------------------------------------------------------|---------------------------------|
| Padrão                                                                                    | `sticky_strict off;`            |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream                        |

Quando habilitado, faz com que o Angie retorne um erro HTTP 502 para o cliente
se o servidor desejado estiver indisponível,
em vez de usar qualquer outro servidor disponível
como faria quando nenhum servidor no upstream estiver disponível.

<a id="index-19"></a>

<a id="u-upstream"></a>

### upstream

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `upstream` name { ... }   |
|-------------------------------------------------------------------------------------------|---------------------------|
| Padrão                                                                                    | —                         |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | http                      |

Define um grupo de servidores. Os servidores podem escutar em portas diferentes. Além disso, servidores escutando em sockets TCP e de domínio UNIX podem ser misturados.

Exemplo:

```nginx
upstream backend {
    server backend1.example.com weight=5;
    server 127.0.0.1:8080       max_fails=3 fail_timeout=30s;
    server backup1.example.com  backup;
}
```

<a id="round-robin"></a>

Por padrão, as requisições são distribuídas entre os servidores usando um método de balanceamento round-robin ponderado. No exemplo acima, cada 7 requisições serão distribuídas da seguinte forma: 5 requisições vão para backend1.example.com e uma requisição para cada um dos segundo e terceiro servidores.

Se ocorrer um erro durante a comunicação com um servidor, a requisição será passada para o próximo servidor, e assim por diante até que todos os servidores funcionais sejam tentados. Se uma resposta bem-sucedida não puder ser obtida de nenhum dos servidores, o cliente receberá o resultado da comunicação com o último servidor.

<a id="index-20"></a>

<a id="u-zone"></a>

### zone

| [Sintaxe](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)   | `zone` name [size];   |
|-------------------------------------------------------------------------------------------|-----------------------|
| Padrão                                                                                    | —                     |
| [Contexto](https://pt.angie.software//angie/docs/configuration/configfile.md#configfile)  | upstream              |

Define o nome e tamanho da zona de memória compartilhada que mantém a configuração do grupo e o estado de tempo de execução que são compartilhados entre os processos worker. Vários grupos podem compartilhar a mesma zona. Neste caso, é suficiente especificar o tamanho apenas uma vez.

#### NOTE
O conteúdo da zona só é preservado na recarga quando o `size`
configurado não muda. Qualquer alteração de tamanho — aumento ou
redução — faz com que a zona seja recriada vazia.

<a id="built-in-variables-14"></a>

## Variáveis Integradas

O módulo `http_upstream` suporta as seguintes variáveis integradas:

<a id="v-sticky-sessid"></a>

### `$sticky_sessid`

Usada com `remote_action` em [sticky](#u-sticky);
armazena o ID de sessão inicial obtido de `lookup`.

<a id="v-sticky-sid"></a>

### `$sticky_sid`

Usada com `remote_action` em [sticky](#u-sticky);
armazena o ID do servidor previamente associado com a sessão.

<a id="v-upstream-addr"></a>

### `$upstream_addr`

armazena o endereço IP e porta, ou o caminho para o socket de domínio UNIX do servidor upstream. Se vários servidores foram contatados durante o processamento da requisição, seus endereços são separados por vírgulas, por exemplo:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock

Se um redirecionamento interno de um grupo de servidores para outro acontecer, iniciado por `X-Accel-Redirect` ou [error_page](https://pt.angie.software//angie/docs/configuration/modules/http/index.md#error-page), então os endereços dos servidores de diferentes grupos são separados por dois pontos, por exemplo:

> 192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80

Se um servidor não puder ser selecionado, a variável mantém o nome do [grupo de servidores](#u-upstream).

<a id="v-upstream-bytes-received"></a>

### `$upstream_bytes_received`

número de bytes recebidos de um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-bytes-sent"></a>

### `$upstream_bytes_sent`

número de bytes enviados para um servidor upstream. Valores de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-cache-status"></a>

### `$upstream_cache_status`

mantém o status de acesso a um cache de resposta. O status pode ser
`MISS`, `BYPASS`, `EXPIRED`, `STALE`, `UPDATING`,
`REVALIDATED`, ou `HIT`:

- `MISS`: A resposta não é encontrada no cache,
  e a requisição é passada para o servidor upstream.
- `BYPASS`: O cache é ignorado,
  e a requisição é passada diretamente para o servidor upstream.
- `EXPIRED`: A resposta em cache está obsoleta,
  e uma nova requisição é passada para o servidor upstream para atualizar o conteúdo.
- `STALE`: A resposta em cache está obsoleta,
  mas ainda é servida aos clientes
  até que o conteúdo seja eventualmente atualizado do servidor upstream.
- `UPDATING`: A resposta em cache está obsoleta,
  mas ainda é servida aos clientes
  enquanto a atualização atualmente em andamento do servidor upstream está em progresso.
- `REVALIDATED`: A resposta em cache está obsoleta,
  mas foi revalidada com sucesso
  e não precisa ser atualizada do servidor upstream.
- `HIT`: A resposta foi obtida do cache.

Se a requisição ignorou o cache sem acessá-lo,
a variável não é definida.

<a id="v-upstream-cache-key"></a>

### `$upstream_cache_key`

contém a chave de cache usada para a requisição.

<a id="v-upstream-connect-time"></a>

### `$upstream_connect_time`

mantém o tempo gasto estabelecendo uma conexão com o servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. No caso de SSL, inclui o tempo gasto no handshake. Tempos de várias conexões são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-cookie"></a>

### `$upstream_cookie_<name>`

cookie com o nome especificado enviado pelo servidor upstream no campo de cabeçalho de resposta `Set-Cookie`. Apenas os cookies da resposta do último servidor são salvos.

<a id="v-upstream-header-time"></a>

### `$upstream_header_time`

mantém o tempo gasto recebendo o cabeçalho de resposta do servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias respostas são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-http"></a>

### `$upstream_http_<name>`

mantém campos de cabeçalho de resposta do servidor. Por exemplo, o campo de cabeçalho de resposta `Server` está disponível através da variável `$upstream_http_server`. As regras de conversão de nomes de campos de cabeçalho para nomes de variáveis são as mesmas para as variáveis que começam com o prefixo `$http_`. Apenas os campos de cabeçalho da resposta do último servidor são salvos.

<a id="v-upstream-request-method"></a>

### `$upstream_request_method`

método de requisição usado para a requisição upstream. Ele pode diferir do método da
requisição do cliente quando o cache converte `HEAD` para `GET` ou quando
[proxy_method](https://pt.angie.software//angie/docs/configuration/modules/http/http_proxy.md#proxy-method) é definido.

<a id="v-upstream-queue-time"></a>

### `$upstream_queue_time`

mantém o tempo que a requisição passou na [fila](#u-queue)
antes da próxima seleção de servidor;
o tempo é mantido em segundos com resolução de milissegundos.
Tempos de várias tentativas são separados por vírgulas e dois pontos
como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-response-length"></a>

### `$upstream_response_length`

mantém o comprimento da resposta obtida do servidor upstream; o comprimento é mantido em bytes. Comprimentos de várias respostas são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-response-time"></a>

### `$upstream_response_time`

mantém o tempo gasto recebendo a resposta do servidor upstream; o tempo é mantido em segundos com resolução de milissegundos. Tempos de várias respostas são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-status"></a>

### `$upstream_status`

mantém o código de status da resposta obtida do servidor upstream. Códigos de status de várias respostas são separados por vírgulas e dois pontos como endereços na variável [$upstream_addr](#v-upstream-addr). Se um servidor não puder ser selecionado, a variável mantém o código de status 502 (Bad Gateway).

<a id="v-upstream-sticky-status"></a>

### `$upstream_sticky_status`

Status de requisições sticky.

| `""`   | Requisição enviada para um upstream onde sticky não está habilitado.                                                |
|--------|---------------------------------------------------------------------------------------------------------------------|
| `NEW`  | Requisição não contém informação sticky.                                                                            |
| `HIT`  | Requisição com informação sticky enviada para o servidor desejado.                                                  |
| `MISS` | Requisição com informação sticky enviada para um servidor<br/>selecionado pelo algoritmo de balanceamento de carga. |

Status de várias conexões são separados por vírgulas e dois pontos
como endereços na variável [$upstream_addr](#v-upstream-addr).

<a id="v-upstream-trailer"></a>

### `$upstream_trailer_<name>`

mantém campos do final da resposta obtida do servidor upstream.