diff --git a/documentation/content/pt-br/articles/building-products/_index.adoc b/documentation/content/pt-br/articles/building-products/_index.adoc index 41835e5254..4a57bf414a 100644 --- a/documentation/content/pt-br/articles/building-products/_index.adoc +++ b/documentation/content/pt-br/articles/building-products/_index.adoc @@ -1,334 +1,335 @@ --- title: Construindo Produtos com o FreeBSD authors: - author: Joseph Koshy email: jkoshy@FreeBSD.org organizations: - organization: The FreeBSD Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Construindo Produtos com o FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo -include::shared/pt-br/urls.adoc[] - ifeval::["{backend}" == "html5"] +include::shared/pt-br/urls.adoc[] :imagesdir: ../../../images/articles/building-products/ endif::[] ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/building-products/ endif::[] ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/building-products/ endif::[] [.abstract-title] Sumário O projeto FreeBSD é um projeto voluntário e colaborativo de âmbito mundial, o qual desenvolve um sistema operacional de alta qualidade, capaz de ser utilizado em diferentes arquiteturas computacionais. O projeto FreeBSD distribui o código fonte do seu produto sob uma licença liberal, com a intenção de incentivar o uso de seu código. Colaborar com o projeto FreeBSD pode ajudar sua empresa a reduzir o tempo necessário para colocar um produto no mercado, a reduzir seus custos de engenharia e a melhorar qualidade de seus produtos. Este artigo analisa as questões envolvidas no uso do código do FreeBSD em appliances e softwares. Ele também destaca as características do FreeBSD, que o tornam uma excelente base para o desenvolvimento de produtos. O artigo conclui sugerindo um conjunto das "melhores práticas" de organizações que colaboram com o projeto FreeBSD. ''' toc::[] [[introduction]] == Introdução Atualmente o FreeBSD é bem conhecido como um sistema operacional de alto desempenho para servidores. Ele está instalado em milhões de servidores web e em outros hosts conectados diretamente a internet em todo o mundo. O código do FreeBSD também é parte integrante de muitos produtos, que vão desde aparelhos como roteadores de rede, firewalls e dispositivos de armazenamento, até computadores pessoais. Partes do FreeBSD também têm sido utilizadas em softwares comerciais (consulte <>). Neste artigo, vamos olhar para o link:https://www.FreeBSD.org/[projeto FreeBSD] como um recurso de engenharia de software --como um conjunto de blocos de construção e de processos os quais você pode utilizar para construir produtos. Embora o código fonte do FreeBSD seja distribuído gratuitamente ao público, para desfrutar plenamente dos benefícios do trabalho do projeto, as organizações precisam _colaborar_ com o mesmo. Nas seções subsequentes do presente artigo discutiremos formas eficazes de colaborar com o projeto, bem como os perigos que precisam ser evitados ao fazê-lo. *Aviso ao Leitor.* O autor considera que as características do projeto FreeBSD mencionadas neste artigo eram substancialmente verdadeiras no momento em que o artigo foi concebido e escrito (2005). No entanto, o leitor deve ter em mente que as práticas e processos utilizados por comunidades de código aberto podem mudar ao longo do tempo, e que portanto as informações deste artigo devem ser consideradas apenas como indicativas e não como verdades absolutas. === Público Alvo Este documento tem como público alvo os seguintes grupos de pessoas: * Tomadores de decisão em empresas que estejam em busca de meios para melhorar a qualidade de seus produtos, de reduzir o tempo necessário para lançá-los no mercado e de reduzir seus custos de engenharia no longo prazo. * Consultores de tecnologia procurando as melhores práticas para alavancar projetos de "código aberto". * Observadores da indústria interessados em compreender a dinâmica dos projetos de código aberto. * Desenvolvedores de software que utilizam o FreeBSD e que buscam formas de contribuir com o projeto. === Objetivos do artigo Após a leitura deste artigo, você deve ter: * Uma melhor compreensão dos objetivos do Projeto FreeBSD e de sua estrutura organizacional. * Uma visão geral das tecnologias disponíveis no projeto. * Uma melhor compreensão do modelo de desenvolvimento adotado pelo Projeto FreeBSD e dos processos de engenharia envolvidos no lançamento de uma nova versão do sistema. * Consciência dos canais de comunicação utilizados pelo projeto e do nível de transparência que você pode esperar. * Consciência das melhores formas de se trabalhar com o projeto--a melhor forma de reduzir os custos de engenharia, de reduzir o tempo necessário para levar seu produto ao mercado, de gerir vulnerabilidades de segurança, e de preservar a compatibilidade futura com o seu produto a medida que o Projeto FreeBSD evolui. === Estrutura do Artigo O restante deste artigo está estruturado da seguinte forma: * A <> apresenta o projeto FreeBSD, explora sua estrutura organizacional, as principais tecnologias e processos de engenharia envolvidos no lançamento de uma nova versão do sistema. * A <> descreve formas de colaborar com o Projeto FreeBSD. Esta seção também aborda as armadilhas que são geralmente encontradas por empresas que trabalham com projetos voluntários como o FreeBSD. * A <> conclui o artigo. [[freebsd-intro]] == O FreeBSD como um conjunto de blocos de construção O FreeBSD fornece uma excelente base sobre a qual podemos construir produtos: * O código fonte do FreeBSD é distribuído sob uma licença BSD liberal, o que facilita sua adoção em produtos comerciais <> com um mínimo de preocupações. * O Projeto FreeBSD possui excelentes práticas de engenharia as quais podem ser aproveitadas. * O projeto oferece uma transparência excepcional em seu funcionamento, permitindo que as empresas que utilizam o seu código se planejem de forma eficaz para o futuro. * A cultura do projeto FreeBSD, herdada do Grupo de Pesquisa de Ciências da Computação da Universidade da Califórnia em Berkeley <>, fomenta trabalhos de alta qualidade. Algumas funcionalidades do FreeBSD definem o estado da arte. O <> analisa em maior profundidade os motivos comerciais para se utilizar código fonte aberto. Para as organizações, os benefícios do uso de componentes do FreeBSD em seus produtos incluem a redução do tempo necessário para lançar novos produtos no mercado, menores custos e menores riscos de desenvolvimento. === Construindo com o FreeBSD Aqui estão alguns exemplos de como as empresas estão utilizando o FreeBSD: * Como um provedor (upstream source) de códigos testados para bibliotecas e utilitários. + Sendo o "downstream" do projeto, as organizações se aproveitam das novas funcionalidades, das correções de bugs e dos testes que o código fonte do projeto FreeBSD recebe. * Como sistema operacional integrado (por exemplo, em um roteador OEM e ou em um dispositivo de firewall). Neste modelo, as empresas utilizam uma versão customizada do kernel e do conjunto de aplicativos do FreeBSD, juntamente com uma camada proprietária de gestão para os seus dispositivos. Os fabricantes de equipamentos originais (OEMs) se beneficiam da adição por parte do FreeBSD de suporte a novos componentes de hardware, bem como se beneficia dos testes que o sistema base recebe. + O FreeBSD é distribuído com um ambiente de desenvolvimento auto-hospedado o qual permite a fácil criação de tais configurações. * Como um ambiente Unix compatível para as funções de gerenciamento em dispositivos de armazenamento high-end e em dispositivos de rede, executando em uma lâmina separada "blade". + O FreeBSD fornece ferramentas para a criação de imagens do sistema operacional dedicadas a executar uma função específica. Sua implementação da API unix BSD é madura e testada. O FreeBSD também pode proporcionar um ambiente de desenvolvimento cruzado estável para os outros componentes de dispositivos topo de linha. * Como um veículo para obter suporte e testes amplos de uma equipe mundial de desenvolvedores para a sua "propriedade intelectual" não-crítica. + Neste modelo, as organizações contribuem com frameworks de infra-estrutura úteis ao projeto FreeBSD (por exemplo, veja o man:netgraph[3]). A ampla exposição que o código obtém ajuda na rápida identificação de bugs e de problemas de desempenho. O envolvimento de desenvolvedores de alta qualidade também resulta no desenvolvimento de extensões úteis para a infra-estrutura do sistema, e das quais a empresa que está contribuindo com o projeto também se beneficia. * Como um ambiente de desenvolvimento apoiando desenvolvimento cruzado para sistemas operacionais embarcados como http://www.rtems.com/[RTEMS] e o http://ecos.sourceware.org/[eCOS]. + Existem muitos ambientes de desenvolvimento completos na forte coleção de mais de 24,000 aplicativos portados e empacotados para o FreeBSD. * Como forma de suportar uma API estilo Unix em um sistema operacional que de outro modo seria proprietário, aumentando a sua palatabilidade para os desenvolvedores de aplicativos. + Aqui as partes do kernel do FreeBSD e as aplicações são "portadas" para serem executadas juntamente com outras tarefas no sistema operacional proprietário. A disponibilidade de uma implementação estável e bem testada da API Unix(TM) pode reduzir o esforço necessário para portar aplicações populares para um sistema operacional proprietário. Como o FreeBSD é distribuído acompanhado de uma documentação de alta qualidade sobre a sua estrutura interna, e possui processos eficazes de engenharia para gerenciamento de vulnerabilidades e para lançamento de novas versões, os custos para mantê-lo atualizado são baixos. [[freebsd-technologies]] === Tecnologias Existe um grande número de tecnologias suportadas pelo projeto FreeBSD. Abaixo você encontra uma lista com alguma delas: * Um sistema completo que pode compilar a si mesmo para link:https://www.FreeBSD.org/platforms/[muitas arquiteturas:] * Um kernel modular capaz de multiprocessamento simétrico, com módulos de kernel carregáveis e um sistema de configuração flexível e fácil de usar. * Suporta a emulação de binários do Linux(TM) e do SVR4 com velocidades próximas as que você obtém executando os aplicativos de forma nativa. Suporte para os binários dos drivers de rede do Windows(TM) (DIS). * Bibliotecas para muitas tarefas de programação: arquivos, suporte a FTP e HTTP, suporte a threads, além de um ambiente completo de programação POSIX(TM). * Funcionalidades avançadas de segurança: Controle de Acesso Obrigatório (man:mac[9]), jails (man:jail[2]), ACLs, e suporte no kernel a dispositivos de criptografia. * Funcionalidades avançadas de rede: firewalls, gerenciamento de QoS, rede TCP/IP de alta performance com suporte a muitos recursos avançados. + O framework Netgraph (man:netgraph[4]) presente no kernel do FreeBSD, permite que os módulos de rede possam ser conectados entre si de formas flexíveis. * Suporte para tecnologias avançadas de armazenamento Fibre Channel, SCSI, RAID por software e hardware, ATA e SATA. + O FreeBSD suporta um grande numero de sistemas de arquivos, e o seu sistema de arquivos nativo UFS2 suporta soft updates, snapshots e sistemas de arquivos de tamanho muito grandes (até 16 TB por sistema de arquivos) <>. + O framework GEOM GEOM (man:geom[4]) presente no kernel do FreeBSD permite que módulos de armazenamento sejam compostos de forma flexível. * Mais de 24,000 aplicativos portados, tanto comerciais quanto de código aberto, gerenciados através da coleção de ports do FreeBSD. === Estrutura Organizacional A estrutura organizacional do FreeBSD não é hierárquica. Existem basicamente dois tipos de colaboradores no projeto FreeBSD, os usuários em geral e os desenvolvedores com acesso de escrita (conhecidos como _committers_ no jargão) ao repositório de código fonte. Existem muitos milhares de colaboradores no primeiro grupo, a grande maioria das contribuições para o FreeBSD vêm de indivíduos desse grupo; A permissão de commit (acesso de escrita) no repositório é concedida a pessoas que contribuem de forma consistente para o projeto. O direito de commit vem acompanhado de responsabilidades adicionais, e para facilitar o aprendizado das mesmas, um mentor é atribuído a todos os novos committers. .Organização do FreeBSD image::freebsd-organization.png[] A resolução de conflitos é realizada por um "Core Team" de 9 pessoas, o qual é eleito a partir do grupo de committers. O FreeBSD não tem committers "corporativo". Os committers são obrigados a assumir de forma individual a responsabilidade pelas mudanças que introduzem no código. O link:{committers-guide}[FreeBSD Committer's guide]<> documenta as regras e responsabilidades que se aplicam aos committers. O modelo do projeto FreeBSD é examinado em detalhes no <>. === Processos de Engenharia para liberação de novas versões do FreeBSD O processo de engenharia para a liberação de uma nova versão do FreeBSD desempenha um papel importante para assegurar que as suas novas versões sejam de alta qualidade. Em qualquer ponto do tempo, os voluntários do FreeBSD suportam múltiplas versões do código sistema (<>): * As novas funcionalidades e os códigos disruptivos entram na branch de desenvolvimento, também conhecido como branch _-CURRENT_. * A branch _-STABLE_ contém linhas de código que são ramificadas a partir do HEAD em intervalos regulares. Apenas código devidamente testado é permitido na branch -STABLE. Novas funcionalidades são permitidas após terem sido testadas e estabilizadas na branch -CURRENT. * A branch _-RELEASE_ é mantido pela equipe de segurança do FreeBSD. Somente correções de bugs críticos são permitidos na branch -RELEASE. [[fig-freebsd-branches]] .Release Branches do FreeBSD image::freebsd-branches.png[] As linhas de código são mantidas vivas enquanto houver interesse dos usuários e dos desenvolvedores nelas. As arquiteturas de máquina estão agrupadas em "tiers"; As arquiteturas _Tier 1_ são totalmente suportadas pelas equipes de engenharia de lançamento e de segurança, as arquiteturas _Tier 2_ são suportadas em regime de melhores esforços, e as arquiteturas experimentais compreendem o _Tier 3_. A lista das link:{committers-guide}#archs/[arquiteturas suportadas] é parte da coleção de documentos do FreeBSD. A equipe de engenharia de lançamentos publica um link:https://www.FreeBSD.org/releng/[road map] para as versões futuras do FreeBSD no web site do projeto. As datas indicadas no road map não são prazos; As novas versões do FreeBSD são liberadas apenas quando o seu código e documentação estão prontos. O processo de engenharia para a liberação de novas versões do FreeBSD é descrito em detalhes no <>. [[freebsd-collaboration]] == Colaborando com o FreeBSD Projetos open-source como o FreeBSD oferecem códigos finalizados de altíssima qualidade <>. Estudos anteriores examinaram o efeito da disponibilidade do código fonte no desenvolvimento de software <>. Embora o acesso a um código fonte de qualidade possa reduzir o custo inicial de desenvolvimento, a longo prazo, os custos com o gerenciamento de mudanças começam a dominar. A medida que os ambientes computacionais mudam ao longo dos anos e novas vulnerabilidades de segurança são descobertas, o seu produto também precisará mudar e se adaptar. O uso de código open-source não deve ser encarado como uma atividade pontual, mas sim como um __processo contínuo__. Os melhores projetos para se colaborar são os que estão __vivos__, ou seja, aqueles com uma comunidade ativa, que tenha objetivos claros e que possua um estilo de trabalho transparente. * O FreeBSD tem uma comunidade de desenvolvimento ativa em torno dele. No momento em que este artigo foi escrito, existiam milhares de colaboradores com representantes de praticamente todos os continentes povoados do mundo, e mais de 300 indivíduos com acesso de escrita aos repositórios do projeto. * Os objetivos do projeto FreeBSD são <>: ** Desenvolver um sistema operacional de alta qualidade para o hardware de computadores populares, e, ** Tornar o nosso trabalho disponível para todos sob uma licença liberal. * O FreeBSD desfruta de uma cultura aberta e transparente de trabalho. Quase todas as discussões no projeto ocorrem por e-mail, em http://lists.FreeBSD.org/mailman/listinfo[listas publicas de discussão] que também são arquivadas para a posteridade. As políticas do projeto são link:https://www.FreeBSD.org/internal/policies/[documentadas] e mantidas sob controle de revisão. A participação no projeto é aberta a todos. [[freebsd-org]] === Compreendendo a cultura do FreeBSD Para ser capaz de trabalhar de forma eficaz com o projeto FreeBSD, você precisa entender a cultura do projeto. As regras que regem a operação de um projeto voluntário são diferentes das que regem a operação de uma empresa com fins lucrativos. Um erro comum que as empresas cometem ao se aventurar no mundo open-source é o de desvalorizar essas diferenças. *Motivação.* A maioria das contribuições feitas para o FreeBSD são feitas voluntariamente, sem que nenhuma recompensa financeira esteja envolvida. Os fatores que motivam as pessoas são complexos, e vão desde o puro altruísmo até o interesse comum em resolver algum tipo de problema que o FreeBSD esteja tentando resolver. Neste tipo de ambiente, a "elegância jamais é opcional"<>. *Visão de Longo Prazo.* O FreeBSD tem raízes de quase 20 anos para com o trabalho do Grupo de Pesquisa de Ciências da Computação da Universidade da Califórnia, Berkeley.footnote:[O repositório de códigos do FreeBSD contem a história do projeto desde a sua concepção, e existem CDROMs disponíveis que contém código fonte anterior ao CSRG.] Alguns dos desenvolvedores originais do CSRG permanecem associados com o projeto. O projeto valoriza perspectivas de longo prazo <>. Uma sigla encontrada com frequência no projeto DTRT, a qual significa "Faça a Coisa Certa". *Processo de Desenvolvimento.* Programas de computador são ferramentas de comunicacão: em um nível os programadores comunicam as suas intenções usando uma notação precisa para uma ferramenta (um compilador) que traduz as suas instruções para um código executável. Em outro nível, a mesma notação é usada para a comunicação das intenções entre dois programadores. Especificações formais e documentos de design raramente são utilizados no projeto. Código claro e bem escrito, acompanhado de logs bem escritos para as alterações das (<>) são usados em seu lugar. O desenvolvimento do FreeBSD acontece por "consenso áspero e por código sendo executado"<>. [.programlisting] .... r151864 | bde | 2005-10-29 09:34:50 -0700 (Sat, 29 Oct 2005) | 13 lines Changed paths: M /head/lib/msun/src/e_rem_pio2f.c Use double precision to simplify and optimize arg reduction for small and medium size args too: instead of conditionally subtracting a float 17+24, 17+17+24 or 17+17+17+24 bit approximation to pi/2, always subtract a double 33+53 bit one. The float version is now closer to the double version than to old versions of itself -- it uses the same 33+53 bit approximation as the simplest cases in the double version, and where the float version had to switch to the slow general case at |x| == 2^7*pi/2, it now switches at |x| == 2^19*pi/2 the same as the double version. This speeds up arg reduction by a factor of 2 for |x| between 3*pi/4 and 2^7*pi/4, and by a factor of 7 for |x| between 2^7*pi/4 and 2^19*pi/4. .... .Um exemplo de entrada no log de alteração [[fig-change-log]] A comunicação entre os programadores é reforçada pelo uso de um man:style[9] padrão de codificação, comum entre eles. *Canais de Comunicação.* Os colaboradores do FreeBSD estão espalhados por todo o mundo. O email (e em menor extensão, o IRC) é o meio de comunicação preferido no projeto. === Melhores práticas para colaborar com o projeto FreeBSD Agora iremos examinar algumas das melhores práticas para se fazer um melhor uso do FreeBSD no desenvolvimento de produtos. Se planeje para o longo prazo:: Implante processos que o ajudem a monitorar o desenvolvimento do FreeBSD. Por exemplo: + *Acompanhe o código fonte do FreeBSD.* O projeto facilita o espelhamento do seu repositório SVN usando link:{committers-guide}#svn-advanced-use-setting-up-svnsync[svnsync]. Ter o histórico completo do código fonte é útil quando se está debugando problemas complexos e oferece informações valiosas sobre as intenções dos desenvolvedores originais. Utilize um sistema de controle de código que lhe permita mesclar facilmente as alterações entre o código original do FreeBSD e o seu próprio código. + A <> mostra as anotações em uma parte do arquivo referenciado pelo log de alterações da <>. A ascendência de cada linha de código é claramente visível. Listagens com as anotações mostrando a história de cada arquivo que faz parte do FreeBSD estão https://svnweb.freebsd.org/[disponíveis na web]. + [.programlisting] .... #REV #WHO #DATE #TEXT 176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) #include 176410 bde 2008-02-19 07:42:46 -0800 (Tue, 19 Feb 2008) __FBSDID("$FreeBSD: head/pt_BR.ISO8859-1/articles/building-products/article.xml 52185 2018-08-28 03:24:45Z dbaio $"); 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) /* __ieee754_rem_pio2f(x,y) 8870 rgrimes 1995-05-29 22:51:47 -0700 (Mon, 29 May 1995) * 176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * return the remainder of x rem pi/2 in *y 176552 bde 2008-02-25 05:33:20 -0800 (Mon, 25 Feb 2008) * use double precision for everything except passing x 152535 bde 2005-11-16 18:20:04 -0800 (Wed, 16 Nov 2005) * use __kernel_rem_pio2() for large x 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) */ 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) 176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) #include 176465 bde 2008-02-22 07:55:14 -0800 (Fri, 22 Feb 2008) 2116 jkh 1994-08-19 02:40:01 -0700 (Fri, 19 Aug 1994) #include "math.h" .... .Código fonte exibindo a listagem de anotações gerada utilizando o `svn blame` [[fig-svn-blame]] + *Nomeie um guardião.* Nomeie um _guardião_ para monitorar o desenvolvimento do FreeBSD, para manter-se atento a mudanças que poderiam potencialmente afetar os seus produtos. + *Comunique os erros que encontrar de volta para o projeto.* Se você encontrar um bug no código do FreeBSD que você está utilizando, envie um https://www.FreeBSD.org/support/bugreports/[bug report]. Este procedimento simples irá ajudar a garantir que você não precisará corrigir o erro novamente da próxima vez que precisar importar novamente do código base do FreeBSD. Se alavanque nos esforços de engenharia do FreeBSD para lançamento de novas versões:: Utilize código da branch de desenvolvimento -STABLE do FreeBSD. Este branch de desenvolvimento é formalmente suportado pelas equipes de engenharia de lançamento e de segurança, e é formada apenas por código testado. Doe código para reduzir seus custos:: Uma parte significativa dos custos relacionados ao desenvolvimento de um produto é o de realizar a sua manutenção. Ao doar partes não criticas do seu código para o projeto, você se beneficia por ter o seu código exposto de uma forma ampla, exposição que ele não teria de outra forma. Esta exposição por sua vez leva eliminação de um maior numero de bugs e de vulnerabilidades de segurança, e permite que anomalias de desempenho sejam identificadas e corrigidas. Obtenha suporte efetivo:: Para produtos com prazos apertados, é recomendado que você contrate o suporte ou consultoria de um desenvolvedor ou empresa com experiência em FreeBSD. A http://lists.FreeBSD.org/mailman/listinfo/freebsd-jobs[lista de discussão sobre empregos relacionados ao FreeBSD] é um canal de comunicação muito útil para se encontrar talentos. O projeto FreeBSD mantém uma link:https://www.FreeBSD.org/commercial/consult_bycat/[galeria de consultores e empresas de consultoria] que trabalham com FreeBSD. O http://www.bsdcertification.org/[Grupo de Certificação BSD] oferece certificação para todos os principais sistemas operacionais derivados do BSD. + Para as necessidades menos importantes, você pode pedir ajuda nas http://lists.FreeBSD.org/mailman/listinfo[listas de discussão do projeto]. Um guia útil para seguir quando precisar pedir está listado em <>. Divulgue o seu envolvimento:: Você não é obrigado a divulgar que faz uso do FreeBSD, mas ao fazê-lo você estará ajudando ambos os esforços, o seu e o do projeto. + Dar visibilidade para a comunidade FreeBSD de que a sua empresa utiliza o sistema ajuda a melhorar as suas chances de atrair talentos de alta qualidade. Quanto maior for a lista de organizações que apoiam o FreeBSD maior será a presença do sistema na cabeça (mind share) dos desenvolvedores. Ao contribuir para aumentar o numero de desenvolvedores interessados no FreeBSD, você estará gerando uma base saudável para o seu futuro. Suporte os desenvolvedores do FreeBSD:: Às vezes, o caminho mais direto para ver uma funcionalidade que você deseja implementada no FreeBSD é suportar um desenvolvedor que já esteja olhando um problema relacionado. A ajuda pode variar de uma doação de hardware até uma assistência financeira direta. Em alguns países, as doações para o projeto FreeBSD usufruem de benefícios fiscais. O projeto possui umlink:https://www.FreeBSD.org/donations/[canal de comunicação dedicado] para assuntos relacionados a doações e para ajudar os doadores. O projeto também mantém uma página web na qual os desenvolvedores podem link:https://www.FreeBSD.org/donations/wantlist/[listar suas necessidades]. + Por uma política do projeto, o FreeBSD link:{contributors}[reconhece] todas as contribuições recebidas em seu site web. [[conclusion]] == Conclusão O Objetivo do projeto FreeBSD é criar e distribuir o código fonte de um sistema operacional de alta qualidade. Ao trabalhar com o projeto FreeBSD você pode reduzir os seus custos de desenvolvimento e melhorar o tempo necessário para lançar seus novos produtos no mercado em vários cenários de desenvolvimento de produtos. Foram examinadas as características do FreeBSD que o tornam uma excelente opção na estratégia de produto de uma organização. Em seguida, abordamos os aspectos predominantes da cultura do projeto e examinamos formas eficazes de interagir com os seus desenvolvedores. O artigo finaliza com uma lista das melhores práticas que podem ajudar na colaboração da iniciativa privada com o projeto FreeBSD. :sectnums!: [bibliography] == Bibliography [[Carp1996]] [Carp1996] http://www.ietf.org/rfc/rfc1958.txt[The Architectural Principles of the Internet] B. Carpenter. The Internet Architecture Board.The Internet Architecture Board. Copyright(R)1996. [[Com2004]] [Com2004] http://csdl.computer.org/comp/mags/so/2004/01/s1028.pdf[How is Open-Source Affecting Software Development?] Diomidis Spinellis. Clemens Szyperski.IEEE Computer Copyright(R)Jan/Feb 2004. IEEE Computer Society. [[ComGuide]] [ComGuide] link:{committers-guide}[Committer's Guide]The FreeBSD Project. Copyright(R)2005. [[Cov2005]] [Cov2005] http://www.coverity.com/news/nf_news_06_27_05_story_9.html[Coverity study on kernel security holes in Linux and FreeBSD]Coverity Inc.. Copyright(R)2005. [[GoldGab2005]] [GoldGab2005] http://dreamsongs.com/IHE/IHE.html[Innovation Happens Elsewhere: Open Source as Business Strategy] Ron Goldman. Richard Gabriel. Copyright(R)2005. Morgan-Kaufmann. [[Hub1994]] [Hub1994] link:{contributing}[Contributing to the FreeBSD Project] Jordan Hubbard. Copyright(R)1994—2005. The FreeBSD Project. [[McKu1999]] [McKu1999] http://www.usenix.org/publications/library/proceedings/usenix99/mckusick.html[Soft Updates: A Technique for Eliminating Most Synchronous Writes in the Fast Filesystem] Kirk McKusick. Gregory Ganger. Copyright(R)1999. [[McKu1999-1]] [McKu1999-1] http://www.oreilly.com/catalog/opensources/book/kirkmck.html[Twenty Years of Berkeley Unix: From AT&T-Owned to Freely Redistributable] Marshall Kirk McKusick. http://www.oreilly.com/catalog/opensources/book/toc.html[Open Sources: Voices from the Open Source Revolution] O'Reilly Inc.. Copyright(R)1993. [[Mon2005]] [Mon2005] link:{bsdl-gpl}[Why you should use a BSD style license for your Open Source Project] Bruce Montague. The FreeBSD Project. Copyright(R)2005. [[Nik2005]] [Nik2005] link:{dev-model}[A project model for the FreeBSD Project] Niklas Saers. Copyright(R)2005. The FreeBSD Project. [[Nor1993]] [Nor1993] http://www.norvig.com/luv-slides.ps[Tutorial on Good Lisp Programming Style] Peter Norvig. Kent Pitman. Copyright(R)1993. [[Nor2001]] [Nor2001] http://www.norvig.com/21-days.html[Teach Yourself Programming in Ten Years] Peter Norvig. Copyright(R)2001. [[Ray2004]] [Ray2004] http://www.catb.org/~esr/faqs/smart-questions.html[How to ask questions the smart way] Eric Steven Raymond. Copyright(R)2004. [[RelEngDoc]] [RelEngDoc] link:{releng}[FreeBSD Release Engineering] Murray Stokely. Copyright(R)2001. The FreeBSD Project. diff --git a/documentation/content/pt-br/articles/committers-guide/_index.adoc b/documentation/content/pt-br/articles/committers-guide/_index.adoc index 9ca1865fa4..aec05310f4 100644 --- a/documentation/content/pt-br/articles/committers-guide/_index.adoc +++ b/documentation/content/pt-br/articles/committers-guide/_index.adoc @@ -1,2145 +1,2155 @@ --- title: Guia dos Committers authors: - author: Projeto de Documentação do FreeBSD copyright: 1999-2020 Projeto de Documentação do FreeBSD releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "coverity", "ibm", "intel", "sparc", "general"] --- = Guia dos Committers :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este documento fornece informações para a comunidade de committers do FreeBSD. Todos os novos committers devem ler este documento antes de começar, e os committers existentes são fortemente encorajados a revisá-lo de tempos em tempos. Quase todos os desenvolvedores do FreeBSD possuem direitos de commit para um ou mais repositórios. No entanto, alguns desenvolvedores não tem, e algumas das informações aqui se aplicam a eles também. (Por exemplo, algumas pessoas só têm direitos para trabalhar com o banco de dados do Relatório de Problemas). Por favor, veja <> para mais informações. Este documento também pode ser de interesse para os membros da comunidade FreeBSD que querem aprender mais sobre como o projeto funciona. ''' toc::[] [[admin]] == Detalhes Administrativos [.informaltable] [cols="1,1", frame="none"] |=== |_Métodos de login_ | man:ssh[1],_apenas no protocolo 2 |_Servidor Principal de Shell_ |`freefall.FreeBSD.org` |_Servidor SMTP_ |`smtp.FreeBSD.org:587` (veja também <>). |Raiz do Subversion para o `_src/_` |`svn+ssh://repo.FreeBSD.org/base` (veja também <>). |Raiz do Subversion para o `_doc/_` |`svn+ssh://repo.FreeBSD.org/doc` (veja também <>). |Raiz do Subversion para o `_ports/_` |`svn+ssh://repo.FreeBSD.org/ports` (veja também <>). |_Listas de Discussão Internas_ |developers (tecnicamente chamada de all-developers), doc-developers, doc-committers, ports-developers, ports-committers, src-developers, src-committers. (cada repositório do projeto tem as suas próprias listas de discussão -developers e -committers. Os arquivos destas listas podem ser encontrados nos arquivos [.filename]#/local/mail/repository-name-developers-archive# e [.filename]#/local/mail/repository-name-committers-archive# no cluster `FreeBSD.org`.) |_Relatórios mensais do Core Team_ |Disponíveis no diretório [.filename]#/home/core/public/monthly-reports# do cluster `FreeBSD.org`. |_Relatórios mensais da Equipe de Gestão do Ports_ |Disponíveis no diretório [.filename]#/home/portmgr/public/monthly-reports# do cluster `FreeBSD.org`. |_Branchs SVN do `src/` dignas de atenção_ |`stable/n` (`n`-STABLE), `head` (-CURRENT) |=== O man:ssh[1] é necessário para se conectar aos servidores do projeto. Para mais informações, veja <>. Links Úteis: * https://www.FreeBSD.org/internal/[Páginas Internas do Projeto FreeBSD] * https://www.FreeBSD.org/internal/machines/[Servidores do Projeto FreeBSD] * https://www.FreeBSD.org/administration/[Grupos Administrativos do Projeto FreeBSD] [[pgpkeys]] == Chaves OpenPGP para o FreeBSD O projeto FreeBSD utiliza chaves criptográficas em conformidade com o padrão OpenPGP (__Pretty Good Privacy__) para autenticar os committers. Mensagens contendo informações importantes como chaves públicas SSH podem ser assinadas com uma chave OpenPGP para provar que elas vieram realmente do committer. Veja http://www.nostarch.com/pgp_ml.htm[PGP & GPG: Email for the Practical Paranoid by Michael Lucas] e http://en.wikipedia.org/wiki/Pretty_Good_Privacy[] para maiores informações. [[pgpkeys-creating]] === Criando uma chave As chaves existentes podem ser usadas, mas elas devem ser obtidas com o [.filename]#doc/head/shared/pgpkeys/checkkey.sh# primeiro. Neste caso, certifique-se que a chave contenha um ID de usuário FreeBSD. Para quem ainda não tem uma chave OpenPGP, ou precisa de uma nova chave para atender aos requisitos de segurança do FreeBSD, nesta seção iremos mostrar como gerar uma. [[pgpkeys-create-steps]] [.procedure] . Instale o [.filename]#security/gnupg#. Digite estas linhas no [.filename]#~/.gnupg/gpg.conf# para definir padrões mínimos aceitáveis: + [.programlisting] .... fixed-list-mode keyid-format 0xlong personal-digest-preferences SHA512 SHA384 SHA256 SHA224 default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 BZIP2 ZLIB ZIP Uncompressed use-agent verify-options show-uid-validity list-options show-uid-validity sig-notation issuer-fpr@notations.openpgp.fifthhorseman.net=%g cert-digest-algo SHA512 .... . Gere uma chave: + [source,shell] .... % gpg --full-gen-key gpg (GnuPG) 2.1.8; Copyright (C) 2015 Free Software Foundation, Inc. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Warning: using insecure memory! Please select what kind of key you want: (1) RSA and RSA (default) (2) DSA and Elgamal (3) DSA (sign only) (4) RSA (sign only) Your selection? 1 RSA keys may be between 1024 and 4096 bits long. What keysize do you want? (2048) 2048 <.> Requested keysize is 2048 bits Please specify how long the key should be valid. 0 = key does not expire = key expires in n days w = key expires in n weeks m = key expires in n months y = key expires in n years Key is valid for? (0) 3y <.> Key expires at Wed Nov 4 17:20:20 2015 MST Is this correct? (y/N) y GnuPG needs to construct a user ID to identify your key. Real name: Chucky Daemon <.> Email address: notreal@example.com Comment: You selected this USER-ID: "Chucky Daemon " Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o You need a Passphrase to protect your secret key. .... <.> Chaves de 2048-bit com uma expiração de 3 anos proveem uma proteção adequada nos dias de hoje (2013-12). O artigo http://danielpocock.com/rsa-key-sizes-2048-or-4096-bits[] descreve a situação em mais detalhes. <.> Três anos é um tempo de vida para a chave que é curto o suficiente para tornar obsoletas as chaves enfraquecidas pelo avanço do poder computacional, mas é tempo suficiente para reduzir os principais problemas de gerenciamento. <.> Use o seu nome real, preferencialmente o mesmo que consta do seu documento de identificação (ID) emitido pelo seu governo para tornar mais fácil para as outras pessoas confirmarem sua identidade. Você pode inserir um texto adicional para ajudar outras pessoas a identificar você na seção `Comment`. + Depois que o endereço de e-mail é inserido, uma senha é solicitada. Os métodos de criação de uma frase secreta segura são controversos. Em vez de sugerir um único caminho, aqui estão alguns links para sites que descrevem vários métodos: http://world.std.com/~reinhold/diceware.html[], http://www.iusmentis.com/security/passphrasefaq/[], http://xkcd.com/936/[] e http://en.wikipedia.org/wiki/Passphrase[]. Proteja a chave privada e a frase secreta. Se a chave privada ou a frase secreta pode ter sido comprometida ou exposta, notifique imediatamente mailto:accounts@FreeBSD.org[accounts@FreeBSD.org] e revogue a chave. O processo para commit da nova chave é mostrado em <>. [[kerberos-ldap]] == Kerberos e LDAP Web Password para o cluster do FreeBSD O cluster do FreeBSD requer uma senha do Kerberos para acessar certos serviços. A senha do Kerberos também serve como a senha LDAP para a web, já que o LDAP faz um proxy para o Kerberos no cluster. Alguns dos serviços que exigem isso incluem: * https://bugs.freebsd.org/bugzilla[Bugzilla] * https://ci.freebsd.org[Jenkins] Para criar uma nova conta do Kerberos no cluster do FreeBSD, ou para redefinir uma senha do Kerberos para uma conta existente usando um gerador de senha aleatória: [source,shell] .... % ssh kpasswd.freebsd.org .... [NOTE] ==== Isto deve ser feito a partir de uma máquina fora do cluster do FreeBSD.org. ==== Uma senha do Kerberos também pode ser definida manualmente, para isto logue no servidor `freefall.FreeBSD.org` e execute: [source,shell] .... % kpasswd .... [NOTE] ==== A menos que os serviços autenticados por Kerberos do cluster do FreeBSD.org tenham sido usados anteriormente, o erro `Client unknown` será exibido. Este erro significa que o método `ssh kpasswd.freebsd.org` mostrado acima deve ser usado primeiro para inicializar a conta Kerberos. ==== [[committer.types]] == Tipos de Commit Bits O repositório do FreeBSD possui um número de componentes que, quando combinados, suportam os fontes básicos do sistema operacional, a documentação, a infraestrutura de ports de aplicativos de terceiros e vários utilitários mantidos. Quando os commit bits do FreeBSD são alocados, as áreas da árvore onde o bit pode ser usado são especificadas. Geralmente, as áreas associadas a um bit refletem quem autorizou a alocação do bit de commit. Áreas adicionais de autoridade podem ser adicionadas em uma data posterior: quando isso ocorre, o committer deve seguir procedimentos normais de atribuição de bits de confirmação para essa área da árvore, buscando a aprovação da entidade apropriada e possivelmente obtendo um mentor para essa área por algum período de tempo. [.informaltable] [cols="1,1,1", frame="none"] |=== |__Tipo de Committer__ |__Responsável__ |__Componentes da Árvore__ |src |core@ |src/, doc/ sujeito a revisão apropriada |doc |doceng@ |doc/, ports/, src/ documentação |ports |portmgr@ |ports/ |=== Os commit bits alocados antes do desenvolvimento da noção de áreas de autoridade podem ser apropriados para uso em muitas partes da árvore. No entanto, o senso comum determina que um committer que não tenha trabalhado anteriormente em uma área da árvore busque alguém para realizar uma revisão antes de realizar o commit, busque a aprovação da parte responsável apropriada e/ou trabalhe com um mentor. Uma vez que as regras relativas à manutenção de código diferem por área da árvore, isso é tanto para o benefício do committer trabalhando em uma área de menos familiar quanto para as outras pessoas trabalhando na árvore. Committers são encorajados a buscar revisão do seu trabalho como parte do processo normal de desenvolvimento, independentemente da área da árvore onde o trabalho está ocorrendo. === Política para atividade de Committers em outras árvores * Todos os committers podem modificar [.filename]#base/head/shared/misc/committers-*.dot#, [.filename]#base/head/usr.bin/calendar/calendars/calendar.freebsd#, e [.filename]#ports/head/astro/xearth/files#. * os doc committers podem efetuar commits de alterações na documentação sob [.filename]#src#, tal como man pages, READMEs, banco de dados do fortune, arquivos de calendários, e comentar correções sem aprovação de um src committer, sujeito aos cuidados normais necessários para um commit seguro. * Qualquer committer pode fazer alterações em qualquer outra árvore com um "Approved by" de um committer que não esteja sob mentoria e que tenha o bit apropriado. * Os committers podem adquirir um bit adicional pelo processo usual de encontrar um mentor que os proporá ao core, doceng ou portmgr, conforme apropriado. Quando aprovados, eles serão adicionados ao 'access' e o período normal de mentoria irá ocorrer, o que envolverá a continuidade do uso do "Approved by" por um período. * O "Approved by" só é aceitável vindo de src committers que não estejam sob mentoria - os committers mentorados podem fornecer um "Reviewed by" mas não um "Approved by". [[subversion-primer]] == Subversion Primer Supõe-se que novos committers já estejam familiarizados com a operação básica do Subversion. Se não, comece lendo o http://svnbook.red-bean.com/[Subversion Book]. [[svn-intro]] === Introdução O repositório de código fonte do FreeBSD mudou do `CVS` para o Subversion em 31 de maio de 2008. O primeiro commit real no `SVN` é o __r179447__. O repositório do FreeBSD `doc/www` foi migrado do `CVS` para o Subversion em 19 de Maio de 2012. O primeiro commit real no `SVN` foi o __r38821__. O repositório da coleção de `ports` do FreeBSD foi migrado do `CVS` para o Subversion em 14 de Julho 2012. O primeiro commit real no `SVN` foi o __r300894__. O Subversion pode ser instalado a partir da Coleção de Ports do FreeBSD, executando o comando: [source,shell] .... # pkg install subversion .... [[svn-getting-started]] === Primeiros Passos Existem algumas maneiras de obter uma cópia de trabalho da árvore do Subversion. Esta seção irá explicá-las. [[svn-getting-started-direct-checkout]] ==== Checkout direto O primeiro é fazer check-out diretamente do repositório principal. Para a árvore `src`, use: [source,shell] .... % svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src .... Para a árvore `doc`, use: [source,shell] .... % svn checkout svn+ssh://repo.freebsd.org/doc/head /usr/doc .... Para a árvore da coleção de `ports`, use: [source,shell] .... % svn checkout svn+ssh://repo.freebsd.org/ports/head /usr/ports .... [NOTE] ==== Embora os exemplos restantes neste documento tenham sido escritos tendo o workflow de trabalho com a árvore `src` em mente, os conceitos básicos são os mesmos para se trabalhar com o `doc` e com a árvore dos `ports`. Os ports relacionados às operações do Subversion estão listados em <>. ==== O comando acima irá fazer o checkout da árvore de código-fonte `CURRENT` como [.filename]#/usr/src/#, o qual pode ser qualquer diretório de destino no sistema de arquivos local. Omitir o argumento final desse comando faz com que a cópia de trabalho, neste caso, seja nominada como "head", mas ela poderá ser renomeada com segurança. O `svn+ssh` significa que o protocolo `SVN` será tunelado sobre o SSH. O nome do servidor é `repo.freebsd.org`, e `base` é o caminho para o repositório, e `head` é o subdiretório dentro do repositório. Se seu nome de login no projeto FreeBSD for diferente do nome de login usado na sua máquina local, inclua-o na URL (por exemplo `svn+ssh://jarjar@repo.freebsd.org/base/head`) ou adicione uma entrada no arquivo [.filename]#~/.ssh/config# no formato: [.programlisting] .... Host repo.freebsd.org User jarjar .... Este é o método mais simples, mas é difícil dizer quanta carga ele irá colocar no repositório. [NOTE] ==== O `svn diff` não requer acesso ao servidor pois o `SVN` armazena uma cópia de referência de todos os arquivos na cópia de trabalho. Isto, no entanto, significa que as cópias de trabalho do Subversion são muito grandes em tamanho. ==== [[svn-getting-started-base-layout]] ==== Branches `RELENG_*` e Layout Geral No `svn+ssh://repo.freebsd.org/base`, _base_ refere-se à árvore de código fonte. Similarmente, _ports_ refere-se à árvore de ports e assim por diante. Estes são repositórios separados com suas próprias seqüências de números de mudança, controles de acesso e email de commit. Para o repositório base, HEAD refere-se a árvore -CURRENT. Por exemplo, [.filename]#head/bin/ls# é o que entraria como [.filename]#/usr/src/bin/ls# em uma release. Alguns locais importantes são: * _/head/_ que corresponde a `HEAD`, também conhecido como `-CURRENT`. * _/stable/n_ que corresponde a `RELENG_n_`. * _/releng/n.n_ que corresponde a `RELENG_n_n`. * _/release/n.n.n_ que corresponde a `RELENG_n_n_n_RELEASE`. * _/vendor*_ é uma área de trabalho para importar branches de vendors. Este diretório em si não contém branches, no entanto, os seus subdiretórios contém. Isso contrasta com os diretórios __stable__, _releng_ e __release__. * _/projects_ e _/user_ são áreas de trabalho de branch. Como acima, o diretório _/user_ não contém branches em si. [[svn-getting-started-doc-layout]] ==== Branches e Layout do Projeto de Documentação do FreeBSD no `svn+ssh://repo.freebsd.org/doc`, _doc_ refere-se à raiz do repositório da árvore de código fonte. Em geral, a maior parte do trabalho do Projeto de Documentação do FreeBSD será feito dentro do branch [.filename]#head/# da árvore com os arquivos fontes da documentação. A documentação do FreeBSD é escrita e/ou traduzida para vários idiomas, cada um em um diretório separado no branch [.filename]#head/#. Cada conjunto de tradução contém vários subdiretórios para as várias partes do Projeto de Documentação do FreeBSD. Alguns diretórios notáveis são: * _/articles/_ contém o código fonte para artigos escritos por vários colaboradores do FreeBSD. * _/books/_ contém o código fonte para os diferentes livros, como o Handbook do FreeBSD. * _/htdocs/_ contém o código-fonte do website do FreeBSD. [[svn-getting-started-ports-layout]] ==== Branches e Layout da Árvore de Ports do FreeBSD No `svn+ssh: //repo.freebsd.org/ports`, _ports_ refere-se à raiz do repositório da árvore de ports. Em geral, a maior parte do trabalho na coleção de ports do FreeBSD será feito dentro da branch [.filename]#head/# da árvore de ports, que é a árvore de ports real usada para instalar software. Alguns outros locais importantes são: * /branches/RELENG_n_n_n que corresponde a `RELENG_n_n_n` e é usado para mesclar atualizações de segurança em preparação para uma release. * /tags/RELEASE_n_n_n que corresponde a `RELEASE_n_n_n` e representa uma tag de release da árvore de ports. * /tags/RELEASE_n_EOL representa o tag de end of life de um branch específico do FreeBSD. [[svn-daily-use]] === Uso diário Esta seção explicará como realizar operações comuns do dia-a-dia com o Subversion. [[svn-daily-use-help]] ==== Ajuda O `SVN` traz em si uma documentação interna de ajuda. Ela pode ser acessada digitando: [source,shell] .... % svn help .... Informações adicionais podem ser encontradas no http://svnbook.red-bean.com/[Subversion Book]. [[svn-daily-use-checkout]] ==== Checkout Como visto anteriormente, para fazer o checkout da branch principal (head) do FreeBSD: [source,shell] .... % svn checkout svn+ssh://repo.freebsd.org/base/head /usr/src .... Em algum momento, provavelmente será útil ter uma copia de trabalho mais do que apenas do `HEAD`, por exemplo, ao mesclar as alterações para stable/7. Portanto, pode ser útil ter uma verificação parcial da árvore completa (um check-out completo seria muito doloroso). Para fazer isso, primeiro confira a raiz do repositório: [source,shell] .... % svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base .... Isso vai obter o `base` com todos os arquivos que ele contém (no momento da escrita, apenas o [.filename]#ROADMAP.txt#) e subdiretórios vazios para `head`, `stable`, `vendor` e assim por diante. É possível expandir a cópia de trabalho. Basta alterar a profundidade dos vários subdiretórios: [source,shell] .... % svn up --set-depth=infinity base/head % svn up --set-depth=immediates base/release base/releng base/stable .... O comando acima irá baixar uma cópia completa do `head`, além de cópias vazias de cada tag de `release`, de cada branch de `releng`, e de cada branch `stable`. Se numa data posterior você tiver necessidade de mesclar algo, por exemplo, com a `7-STABLE`, expanda a cópia de trabalho: [source,shell] .... % svn up --set-depth=infinity base/stable/7 .... As subárvores não precisam ser expandidas completamente. Por exemplo, para expandir apenas o `stable/7/sys` e depois expandir o resto do `stable/7`: [source,shell] .... % svn up --set-depth=infinity base/stable/7/sys % svn up --set-depth=infinity base/stable/7 .... Atualizar a árvore com `svn update` irá apenas atualizar o que foi pedido anteriormente (neste caso, `head` e `stable/7`), ele não irá puxar a árvore inteira. [[svn-daily-use-anonymous-checkout]] ==== Checkout Anonimo É possível efetuar o checkout anonimo o repositório Subversion do FreeBSD. Isso dará acesso a uma árvore somente leitura que pode ser atualizada, mas que não poderá ser enviada de volta para o repositório principal por meio de um commit. Para fazer isso, use: [source,shell] .... % svn co https://svn.FreeBSD.org/base/head /usr/src .... Mais detalhes sobre o uso do Subversion podem ser encontrados em link:{handbook}#svn[Usando o Subversion]. [[svn-daily-use-updating-the-tree]] ==== Atualizando a Árvore Para atualizar uma cópia de trabalho para a revisão mais recente ou uma revisão específica: [source,shell] .... % svn update % svn update -r12345 .... [[svn-daily-use-status]] ==== Status Para ver as alterações locais que foram feitas na cópia de trabalho: [source,shell] .... % svn status .... Para mostrar alterações locais e arquivos que estão desatualizados, execute: [source,shell] .... % svn status --show-updates .... [[svn-daily-use-editing-and-committing]] ==== Editando e efetuando o commit O `SVN` não precisa ser avisado com antecedência sobre a edição de arquivos. Para efetuar o commit de todas as alterações no diretório atual e em todos os seus subdiretórios: [source,shell] .... % svn commit .... Para efetuar o commit de todas as alterações, por exemplo, nos arquivos [.filename]#lib/libfetch/# e [.filename]#usr/bin/fetch/# em uma única operação, execute: [source,shell] .... % svn commit lib/libfetch usr/bin/fetch .... Também existe um wrapper de commit para a árvore de ports para manipular as propriedades e para verificar a sanidade das mudanças: [source,shell] .... % /usr/ports/Tools/scripts/psvn commit .... [[svn-daily-use-adding-and-removing]] ==== Adicionando e Removendo Arquivos [NOTE] ==== Antes de adicionar arquivos, obtenha uma cópia do https://people.FreeBSD.org/~peter/auto-props.txt[auto-props.txt] (há também um https://people.FreeBSD.org/~beat/cvs2svn/auto-props.txt[versão específica da árvore de ports]) e adicione-o ao [.filename]#~/.subversion/config# seguindo as instruções contidas no arquivo. Se você adicionou algo antes de ler isto, use o comando `svn rm --keep-local` para apenas os arquivos adicionados, corrija seu arquivo de configuração e adicione-os novamente. O arquivo de configuração inicial é criado quando você executa um comando svn pela primeira vez, até mesmo algo tão simples quanto `svn help`. ==== Os arquivos são adicionados a um `SVN` repositório com `svn add`. Para adicionar um arquivo chamado __foo__, edite-o e depois execute: [source,shell] .... % svn add foo .... [NOTE] ==== A maioria dos novos arquivos fonte deve incluir uma string `$FreeBSD: head/pt_BR.ISO8859-1/articles/committers-guide/article.xml 53731 2020-01-01 14:37:53Z ebrandi $` próxima ao início do arquivo. Ao efetuar o commit, o `svn` expandirá a string `$FreeBSD: head/pt_BR.ISO8859-1/articles/committers-guide/article.xml 53731 2020-01-01 14:37:53Z ebrandi $`, adicionando o caminho do arquivo, o número da revisão, a data e a hora da confirmação e o nome de usuário do committer. Arquivos que não podem ser modificados podem ser enviados sem a string `$FreeBSD: head/pt_BR.ISO8859-1/articles/committers-guide/article.xml 53731 2020-01-01 14:37:53Z ebrandi $`. ==== Os arquivos podem ser removidos com `svn remove`: [source,shell] .... % svn remove foo .... O subversion não requer a exclusão do arquivo antes de usaramos o comando `svn rm` e, de fato, ele reclama se isso acontecer. É possível adicionar diretórios com `svn add`: [source,shell] .... % mkdir bar % svn add bar .... Apesar que o `svn mkdir` torna isso mais fácil, combinando a criação do diretório e a adição dele: [source,shell] .... % svn mkdir bar .... Como arquivos, os diretórios são removidos com `svn rm`. Não existe um comando separado especificamente para remover diretórios. [source,shell] .... % svn rm bar .... [[svn-daily-use-copying-and-moving]] ==== Copiando e Movendo Arquivos Este comando cria uma cópia do arquivo [.filename]#foo.c# nomeado [.filename]#bar.c#, com o novo arquivo também sob controle de versão e com o histórico completo de [.filename]#foo.c#: [source,shell] .... % svn copy foo.c bar.c .... Geralmente é preferível copiar desta forma ao invés de copiar o arquivo com comando `cp` e adicionando-o ao repositório com `svn add` porque desta forma o novo arquivo não herda a história do original. Para mover e renomear um arquivo: [source,shell] .... % svn move foo.c bar.c .... [[svn-daily-use-log-and-annotate]] ==== Logs e Anotações O `svn log` mostra revisões e mensagens de commit, as mais recentes são exibidas primeiro, para arquivos ou diretórios. Quando usado em um diretório, todas as revisões que afetaram o diretório e os arquivos nesse diretório são mostradas. O `svn annotate` , ou igualmente o `svn praise` ou `svn blame`, mostra o número de revisão mais recente e quem fez o commit dessa revisão para cada linha de um arquivo. [[svn-daily-use-diffs]] ==== Diffs O `svn diff` exibe alterações na cópia de trabalho. Diffs gerado por `SVN` são unificados e incluem novos arquivos por padrão na saída do diff. O `svn diff` pode mostrar as mudanças entre duas revisões do mesmo arquivo: [source,shell] .... % svn diff -r179453:179454 ROADMAP.txt .... Ele também pode mostrar todas as alterações para um changeset específico. Este comando mostra quais alterações foram feitas no diretório atual e em todos os subdiretórios do changeset 179454: [source,shell] .... % svn diff -c179454 . .... [[svn-daily-use-reverting]] ==== Revertendo Mudanças locais (incluindo adições e deleções) podem ser revertidas usando `svn revert`. Ele não atualiza arquivos desatualizados, apenas os substitui por cópias originais da versão original. [[svn-daily-use-conflicts]] ==== Conflitos Se um `svn update` resultou em um conflito de mesclagem, o Subversion irá lembrar quais arquivos têm conflitos e se recusará a fazer o commit de quaisquer alterações nesses arquivos até que seja explicitamente informado que os conflitos foram resolvidos. O procedimento simples, ainda não obsoleto, é: [source,shell] .... % svn resolved foo .... No entanto, o procedimento preferido é: [source,shell] .... % svn resolve --accept=working foo .... Os dois exemplos são equivalentes. Os valores possíveis para `--accept` são: * `working`: use a versão em seu diretório de trabalho (a qual se presume que foi editada para resolver os conflitos). * `base`: usar uma cópia original da versão que você tinha antes do `svn update`, descartando suas próprias alterações, as mudanças conflitantes e possivelmente outras mudanças intervenientes também. * `mine-full`: use o que você tinha antes do `svn update`, incluindo suas próprias mudanças, mas descartando as mudanças conflitantes, e possivelmente outras mudanças intervenientes também. * `theirs-full`: use a versão que foi recuperada quando você fez o `svn update`, descartando as suas próprias mudanças. === Uso Avançado [[svn-advanced-use-sparse-checkouts]] ==== Checkouts dispersos O `SVN` permite __sparse__, ou checkouts parciais de um diretório adicionando `--depth` a um `svn checkout`. Os argumentos válidos para `--depth` são: * `empty`: o próprio diretório sem qualquer conteúdo. * `files`: o diretório e quaisquer arquivos nele contidos. * `immediates`: o diretório e quaisquer arquivos e diretórios contidos nele, mas nenhum dos conteúdos dos subdiretórios. * `infinity`: qualquer coisa. A opção `--depth` se aplica a muitos outros comandos, incluindo `svn commit`, `svn revert` e o `svn diff`. Como o parâmetro `--depth` utilizado é persistente, existe uma opção `--set-depth` para o `svn update` que irá mudar a profundidade selecionada. Assim, dada a cópia de trabalho produzida pelo exemplo anterior: [source,shell] .... % cd ~/freebsd % svn update --set-depth=immediates . .... O comando acima irá popular a cópia de trabalho em _~/freebsd_ com [.filename]#ROADMAP.txt# e subdiretórios vazios, e nada acontecerá quando `svn update` for executado nos subdiretórios. No entanto, esse comando definirá a profundidade para _head_ (nesse caso) como infinito e o populará totalmente: [source,shell] .... % svn update --set-depth=infinity head .... [[svn-advanced-use-direct-operation]] ==== Operação Direta Certas operações podem ser realizadas diretamente no repositório sem tocar na cópia de trabalho. Especificamente, isso se aplica a qualquer operação que não exija a edição de um arquivo, incluindo: * `log`, `diff` * `mkdir` * `remove`, `copy`, `rename` * `propset`, `propedit`, `propdel` * `merge` A criação de uma branch é muito rápida. Este comando seria usado para criar a branch `RELENG_8`: [source,shell] .... % svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/stable/8 .... Isso equivale a esses comandos, que levam minutos e horas, em vez de segundos, dependendo da sua conexão de rede: [source,shell] .... % svn checkout --depth=immediates svn+ssh://repo.freebsd.org/base % cd base % svn update --set-depth=infinity head % svn copy head stable/8 % svn commit stable/8 .... [[svn-advanced-use-merging]] ==== Mesclando com `SVN` Esta seção lida com o merge de código de um branch para outro (normalmente, do head para um brach stable). [NOTE] ==== Em todos os exemplos abaixo, `$FSVN` refere-se à localização do repositório Subversion do FreeBSD, `svn+ssh://repo.freebsd.org/base`. ==== ===== Sobre o acompanhamento de mesclagem Do ponto de vista do usuário, informações de acompanhamento de mesclagem (ou mergeinfo) são armazenadas em uma propriedade chamada `svn:mergeinfo`, que é uma lista separada por vírgulas de revisões e intervalos de revisões que foram mescladas. Quando definido em um arquivo, ele se aplica somente a esse arquivo. Quando definido em um diretório, ele se aplica a esse diretório e seus descendentes (arquivos e diretórios), exceto aqueles que possuem o seu próprio `svn:mergeinfo`. Ele _não_ é herdado. Por exemplo, [.filename]#stable/6/contrib/openpam/# não herda implicitamente o mergeinfo de [.filename]#stable/6/#, ou do [.filename]#stable/6/contrib/#. Isso faria com que os checkouts parciais fossem difíceis de gerenciar. Em vez disso, o mergeinfo é explicitamente propagado pela árvore. Para mesclar algo em [.filename]#branch/foo/bar/#, estas regras se aplicam: . Se [.filename]#branch/foo/bar/# ainda não tiver um registro mergeinfo, mas um ancestral direto (por exemplo, [.filename]#branch/foo/#) tem, então esse registro será propagado para abaixo até [.filename]#branch/foo/bar/# antes que as informações sobre a mesclagem atual sejam registradas. . As informações sobre a mesclagem atual _não_ serão propagadas para o ancestral. . Se um descendente direto de [.filename]#branch/foo/bar/# (por exemplo, [.filename]#branch/foo/bar/baz/#) já tiver um registro mergeinfo, as informações sobre a mesclagem atual serão propagadas para ele. Se você considerar o caso em que uma revisão altera várias partes separadas da árvore (por exemplo, [.filename]#branch/foo/bar/# e [.filename]#branch/foo/quux/#), mas você só deseja mesclar alguns deles (por exemplo, [.filename]#branch/foo/bar/#), você verá que essas regras fazem sentido. Se mergeinfo fosse propagado, pareceria que a revisão também foi mesclada com [.filename]#branch/foo/quux/#, quando na verdade não foi. [[merge-source]] ===== Selecionando a branch de origem e de destino ao mesclar Mesclagens para as branches `stable/` devem originar-se da `head/`. Por exemplo: [source,shell] .... svn merge -c r123456 ^/head/ stable/11 svn commit stable/11 .... Mesclagens para as branches `releng/` devem sempre se originar da branch `stable/` correspondente. Por exemplo: [source,shell] .... svn merge -c r123456 ^/stable/11 releng/11.0 svn commit releng/11.0 .... [NOTE] ==== Os committers só podem se efetuar um commit para as branches `releng/` durante um ciclo de release após receber aprovação da Equipe de Engenharia de Release, após o qual somente o Security Officer pode efetuar commits para o branch `releng/` para um Aviso de Segurança ou Aviso de Errata. ==== Todas as mesclagens são mescladas e enviadas por commit a partir da raiz da branch. Todas as mesclagens se parecem com: [source,shell] .... svn merge -cr123456 ^/head/checkout svn commit checkout .... Observe que _checkout_ deve ser uma verificação completa da branch na qual a mesclagem ocorre. [source,shell] .... svn merge -c r123456 ^/stable/10 releng/10.0 .... ===== Preparando o Alvo de Mesclagem (Merge Target) Devido aos problemas de propagação do mergeinfo descritos anteriormente, é muito importante nunca mesclar as alterações em uma cópia de trabalho esparsa. Sempre use um checkout completo do branch que está sendo mesclado. Por exemplo, ao mesclar de HEAD para 7, use um checkout completo de stable/7: [source,shell] .... % cd stable/7 % svn up --set-depth=infinity .... O diretório de destino também deve estar atualizado e não deve conter alterações que ainda não foram enviadas por commit ou arquivos perdidos. ===== Identificando Revisões Identificar revisões a serem mescladas é uma obrigação. Se o alvo já tiver mergeinfo completo, solicite uma lista para o `SVN`: [source,shell] .... % cd stable/6/contrib/openpam % svn mergeinfo --show-revs=eligible $FSVN/head/contrib/openpam .... Se o destino não tiver mergeinfo completo, verifique o log da origem de mesclagem. ===== Mesclando Agora vamos começar a mesclar! ====== Os princípios Por exemplo, para mesclar: * revisão `$R` * no diretório $target na branch stable $B * a partir do diretório $source no head * $FSVN é o `svn+ssh://repo.freebsd.org/base` Supondo que as revisões $P e $Q já tenham sido mescladas e que o diretório atual seja uma cópia de trabalho atualizada de stable/$B, a mergeinfo existente será semelhante a: [source,shell] .... % svn propget svn:mergeinfo -R $target $target - /head/$source:$P,$Q .... A mesclagem é feita assim: [source,shell] .... % svn merge -c$R $FSVN/head/$source $target .... É possível verificar os resultados disso com um `svn diff`. O svn:mergeinfo agora se parece com: [source,shell] .... % svn propget svn:mergeinfo -R $target $target - head/$source:$P,$Q,$R .... Se os resultados não forem exatamente como os mostrados, você pode precisar de assistência antes de efetuar o commit pois erros podem ter sido cometidos, ou pode haver algo errado com o mergeinfo existente, ou pode haver um bug no Subversion. ====== Exemplo Prático Como um exemplo prático, considere este cenário. As alterações no [.filename]#netmap.4# no r238987 devem ser mescladas do CURRENT para o 9-STABLE. O arquivo reside em [.filename]#head/shared/man/man4#. De acordo com o <>, também é onde devemos fazer a mesclagem. Note que neste exemplo todos os caminhos são relativos ao topo do repositório svn. Para obter mais informações sobre o layout do diretório, consulte <>. O primeiro passo é inspecionar o mergeinfo existente. [source,shell] .... % svn propget svn:mergeinfo -R stable/9/shared/man/man4 .... Tome uma nota rápida de como ele se parece antes de avançar para o próximo passo; fazendo a mesclagem real: [source,shell] .... % svn merge -c r238987 svn+ssh://repo.freebsd.org/base/head/shared/man/man4 stable/9/shared/man/man4 --- Merging r238987 into 'stable/9/shared/man/man4': U stable/9/shared/man/man4/netmap.4 --- Recording mergeinfo for merge of r238987 into 'stable/9/shared/man/man4': U stable/9/shared/man/man4 .... Verifique se o número de revisão da revisão mesclada foi adicionado. Quando isso for verificado, a única coisa que resta é o commit em si. [source,shell] .... % svn commit stable/9/shared/man/man4 .... ===== Precauções antes de efetuar o commit Como sempre, faça um build world (ou as partes apropriadas dele). Verifique as mudanças com o `svn diff` e `svn stat`. Certifique-se de que todos os arquivos que deveriam ter sido adicionados ou excluídos foram de fato adicionados ou excluídos. Dê uma olhada mais de perto em qualquer mudança de propriedade (marcada por um `M` na segunda coluna do `svn stat`). Normalmente, nenhuma propriedade svn:mergeinfo deve estar em qualquer lugar, exceto o diretório (ou diretórios) de destino. Se algo parecer suspeito, peça ajuda. ===== Fazendo o commit Certifique-se de efetuar o commit de um diretório de nível superior para incluir também o mergeinfo. Não especifique arquivos individuais na linha de comando. Para mais informações sobre como submeter arquivos em geral, veja a seção relevante deste manual. [[svn-advanced-use-vendor-imports]] ==== Importações de fornecedores com `SVN` [IMPORTANT] ==== Por favor, leia toda esta seção antes de iniciar uma importação de fornecedores. ==== [NOTE] ==== Os patches para o código do fornecedor se enquadram em duas categorias: * Patches do fornecedor: são patches que foram emitidos pelo fornecedor ou que foram extraídos do sistema de controle de versão do fornecedor, que abordam problemas que não podem esperar até a próxima versão do fornecedor. * Patches do FreeBSD: são patches que modificam o código do fornecedor para resolver problemas específicos do FreeBSD. A natureza de um patch determina para onde ele deve ser enviado por commit: * Os patches do fornecedor devem ser enviados por commit para o branch do fornecedor e mesclados a partir dele. Se o patch resolver um problema em uma nova versão que está sendo importada atualmente, ele _não deve_ ser enviado por commit junto com a nova versão: a versão deve ser importada e marcada primeiro, então a correção pode ser aplicada e o commit efetuado. Não há necessidade de marcar novamente as fontes do fornecedor depois de confirmar o patch. * Patches do FreeBSD são enviados diretamente para o head. ==== ===== Preparando a Árvore Se estiver importando pela primeira vez após a mudança para o Subversion, é necessário achatar e limpar a árvore do fornecedor, bem como inicializar o histórico de mesclagem na árvore principal. ====== Achatamento Durante a conversão do `CVS` para o Subversion, as branches do fornecedor foram importadas com o mesmo layout da árvore principal. Isso significa que as fontes do fornecedor `pf` foram armazenadas originalmente em [.filename]#vendor/pf/dist/contrib/pf#. O código fonte do fornecedor fica melhor se armazenado diretamente em [.filename]#vendor/pf/dist#. Para achatar a árvore do `pf`: [source,shell] .... % cd vendor/pf/dist/contrib/pf % svn mv $(svn list) ../.. % cd ../.. % svn rm contrib % svn propdel -R svn:mergeinfo . % svn commit .... O bit `propdel` é necessário porque, começando com 1.5, o Subversion adicionará `svn:mergeinfo` em qualquer diretório que seja copiado ou movido. Nesse caso, como nada está sendo mesclado da árvore excluída, eles apenas atrapalham. As tags também podem ser achatadas (3, 4, 3.5 etc.); o procedimento é exatamente o mesmo, mudando apenas `dist` para `3.5` ou similar, e aguardando para executar o `svn commit` apenas no final do processo. ====== Limpando A árvore `dist` pode ser limpa conforme necessário. A desativação da expansão de palavras-chave é recomendada, pois não faz sentido no código do fornecedor não modificado e, em alguns casos, pode até mesmo ser prejudicial. O OpenSSH, por exemplo, inclui dois arquivos que se originaram do FreeBSD e ainda contêm as tags da versão original. Para fazer isso: [source,shell] .... % svn propdel svn:keywords -R . % svn commit .... ====== Bootstrapping o historico de mesclagem Se estiver importando pela primeira vez após a mudança para o Subversion, faça o bootstrap do `svn:mergeinfo` no diretório de destino da árvore principal para a revisão que corresponde à última alteração relacionada à árvore do fornecedor, antes de importar novos fontes: [source,shell] .... % cd head/contrib/pf % svn merge --record-only svn+ssh://repo.freebsd.org/base/vendor/pf/dist@180876 . % svn commit .... ===== Importando Novas Fontes Com dois commits - um para a importação em si e outro para a tag - essa etapa pode ser opcionalmente repetida para cada release upstream entre a última importação e a importação atual. ====== Preparando os fontes do fornecedor O Subversion é capaz de armazenar uma distribuição completa na árvore do fornecedor. Portanto, importe tudo, mas mescle apenas o que é necessário. Um `svn add` é necessário para adicionar quaisquer arquivos que foram adicionados desde a última importação do fornecedor, e o `svn rm` é necessário para remover todos os que foram removidos desde então. Recomenda-se a preparação de listas ordenadas do conteúdo da árvore do fornecedor e das fontes que serão importadas, para facilitar o processo. [source,shell] .... % cd vendor/pf/dist % svn list -R | grep -v '/$' | sort >../old % cd ../pf-4.3 % find . -type f | cut -c 3- | sort >../new .... Com esses dois arquivos, o `comm -23 ../old ../new` listará os arquivos removidos (arquivos somente em [.filename]#old#), enquanto `comm -13 .. /old ../new` listará os arquivos adicionados somente no [.filename]#new#. ====== Importando para a Árvore do Fornecedor Agora, os fontes devem ser copiados para [.filename]#dist# e os comandos `svn add` e `svn rm` são usados conforme necessário: [source,shell] .... % cd vendor/pf/pf-4.3 % tar cf - . | tar xf - -C ../dist % cd ../dist % comm -23 ../old ../new | xargs svn rm % comm -13 ../old ../new | xargs svn add --parents .... Se algum diretório foi removido, ele terá que ser removido manualmente com o `svn rm`. Nada vai quebrar se eles não forem, mas eles permanecerão na árvore. Verifique as propriedades em qualquer novo arquivo. Todos os arquivos de texto devem ter o `svn:eol-style` definido como `native`. Todos os arquivos binários devem ter o `svn:mime-type` configurado para `application/octet-stream`, a menos que haja um tipo de mídia mais apropriado. Arquivos executáveis devem ter `svn:executable` definido como `*`. Nenhuma outra propriedade deve existir em qualquer arquivo da árvore. Agora é possível fazer o commit. No entanto, é uma boa prática certificar-se de que tudo está correto, usando os comandos `svn stat` e `svn diff`. ====== Marcação (Tagging) Depois de realizado o commit, as versões do fornecedor são marcadas para referência futura. A melhor e mais rápida maneira de fazer isso é diretamente no repositório: [source,shell] .... % svn cp svn+ssh://repo.freebsd.org/base/vendor/pf/dist svn+ssh://repo.freebsd.org/base/vendor/pf/4.3 .... Quando isso estiver concluído, execute o `svn up` para a cópia de trabalho do [.filename]#vendor/pf# para obter a nova tag, embora isso raramente seja necessário. Se você criar a tag na cópia de trabalho da árvore, os resultados do `svn:mergeinfo` deverão ser removidos: [source,shell] .... % cd vendor/pf % svn cp dist 4.3 % svn propdel svn:mergeinfo -R 4.3 .... ===== Mesclagem para o Head [source,shell] .... % cd head/contrib/pf % svn up % svn merge --accept=postpone svn+ssh://repo.freebsd.org/base/vendor/pf/dist . .... O `--accept=postpone` diz ao Subversion para não reclamar sobre conflitos de mesclagem, pois eles serão manipulados manualmente. [TIP] ==== A mudança do `cvs2svn` ocorreu em 3 de junho de 2008. Ao realizar mesclagens de fornecedores para pacotes que já estavam presentes e convertidos pelo processo `cvs2svn`, o comando usado para mesclar [.filename]#/vendor/package_name/dist# para [.filename]#/head/package_location# (por exemplo, [.filename]#head/contrib/sendmail#) deve usar `-c _REV_` para indicar a revisão a ser mesclada a partir da árvore [.filename]#/vendor#. Por exemplo: [source,shell] .... % svn checkout svn+ssh://repo.freebsd.org/base/head/contrib/sendmail % cd sendmail % svn merge -c r261190 '^/vendor/sendmail/dist' . .... `^` é um alias para o caminho do repositório. ==== [NOTE] ==== Se estiver usando o shell Zsh, o `^` deve ser escapado com `\` ou entre aspas. ==== É necessário resolver quaisquer conflitos de mesclagem. Certifique-se de que todos os arquivos adicionados ou removidos na árvore do fornecedor tenham sido adicionados ou removidos corretamente na árvore principal. Para verificar os diffs com relação ao branch do fornecedor: [source,shell] .... % svn diff --no-diff-deleted --old=svn+ssh://repo.freebsd.org/base/vendor/pf/dist --new=. .... O `--no-diff-deleted` diz ao Subversion para não reclamar sobre os arquivos que estão na árvore do fornecedor, mas que não estão na árvore principal. Coisas que teriam sido removidas antes da importação do fornecedor, como os makefiles do fornecedor e os scripts de configuração. Usando o `CVS`, uma vez que um arquivo estava fora do branch do fornecedor, ele não podia ser colocado de volta. Com o Subversion, não há nenhum conceito dentro ou fora do branch do fornecedor. Se um arquivo que anteriormente tinha modificações locais, para fazer com que ele não apareça em diffs na árvore do fornecedor, tudo o que tem que ser feito é remover qualquer sobra como as tags de versões do FreeBSD, o que é muito mais fácil. Se alguma mudança for necessária para o "world" compilar com os novos fontes, faça-as agora e continue testando até que tudo seja compilado e executado perfeitamente. ===== Fazendo o commit da Importação de Fornecedores Agora é possível fazer o commit! O commit deve ser feito de tudo de uma só vez. Se feito corretamente, a árvore passará de um estado consistente com o código antigo para um estado consistente com o novo código. ===== A partir do zero ====== Importando para a Árvore do Fornecedor Esta seção é um exemplo de importação e marcação do byacc no [.filename]#head#. Primeiro, prepare o diretório em [.filename]#vendor#: [source,shell] .... % svn co --depth immediates $FSVN/vendor % cd vendor % svn mkdir byacc % svn mkdir byacc/dist .... Agora, importe os fontes para o diretório [.filename]#dist#. Uma vez que os arquivos estiverem no lugar, faça o `svn add` dos novos, e então faça o `svn commit` e aplique a tag na versão importada. Para poupar tempo e largura de banda, é possível efetuar diretamente o commit e as marcações de forma remota: [source,shell] .... % svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115 .... ====== Mesclando para o `head` Devido a este ser um novo arquivo, copie-o para a mesclagem: [source,shell] .... % svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc .... Ainda é possível trabalhar normalmente nos fontes recém importados. [[svn-advanced-use-reverting-a-commit]] ==== Revertendo um Commit A reversão de um commit para uma versão anterior é bem fácil: [source,shell] .... % svn merge -r179454:179453 ROADMAP.txt % svn commit .... Alterar a sintaxe do número, com o negativo significando a reversão de uma mudança, também pode ser usado: [source,shell] .... % svn merge -c -179454 ROADMAP.txt % svn commit .... Isso também pode ser feito diretamente no repositório: [source,shell] .... % svn merge -r179454:179453 svn+ssh://repo.freebsd.org/base/ROADMAP.txt .... [NOTE] ==== É importante assegurar que o mergeinfo esteja correto ao reverter um arquivo para permitir que o `svn mergeinfo --eligible` funcione como esperado. ==== A reversão da exclusão de um arquivo é um pouco diferente. É necessário copiar a versão do arquivo que antecede a exclusão. Por exemplo, para restaurar um arquivo que foi excluído na revisão N, restaure a versão N-1: [source,shell] .... % svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 % svn commit .... ou, igualmente: [source,shell] .... % svn copy svn+ssh://repo.freebsd.org/base/ROADMAP.txt@179454 svn+ssh://repo.freebsd.org/base .... Simplesmente _não_ recrie o arquivo manualmente e o adicione com o `svn add` - isso fará com que o histórico seja perdido. [[svn-advanced-use-fixing-mistakes]] ==== Corrigindo Erros Por mais que possamos realizar uma cirurgia em uma emergência, não planeje ou corrija erros por baixo dos panos. Planos para erros permanecem nos registros para sempre. Certifique-se de verificar a saída do `svn status` e do `svn diff` antes de enviar o commit. Erros acontecerão, mas eles geralmente podem ser corrigidos sem perturbar. No caso de adicionar um arquivo no local errado. A coisa certa a fazer é usar o `svn move` e mover o arquivo para o local correto e fazer o commit. Isso altera apenas algumas linhas de metadados no journal do repositório, e os logs serão todos conectados corretamente. A coisa errada a fazer é apagar o arquivo e, em seguida, usar `svn add` para adicionar uma cópia independente no local correto. Em vez de algumas linhas de texto, o repositório journal cria uma nova cópia inteira do arquivo. Isso é um desperdício. [[svn-getting-started-checkout-from-a-mirror]] ==== Usando um Espelho do Subversion Há uma séria desvantagem neste método: toda vez que for feito o commit de algo, terá que executar um `svn relocate` no repositório master, não esquecendo de executar o `svn relocate` de volta para o mirror após o commit. Além disso, como o `svn relocate` só funciona entre os repositórios que possuem o mesmo UUID, algum hacking do UUID do repositório local deve ocorrer antes que seja possível começar a usá-lo. [[svn-advanced-checkout-from-mirror]] ===== Checkout a partir de um Mirror Faça o checkout de uma cópia de trabalho a partir de um mirror substituindo a URL do mirror por `svn+ssh://repo.freebsd.org/base`. Este pode ser um mirror oficial ou um mirror mantido usando o `svnsync`. [[svn-advanced-use-setting-up-svnsync]] ===== Configurando um Mirror svnsync Evite configurar um mirror svnsync a menos que haja uma boa razão para isso. Na maioria das vezes, um mirror `git` é uma alternativa melhor. Começar um novo mirror do zero leva muito tempo. Espere um mínimo de 10 horas para conectividade de alta velocidade. Se o trafego for passar por links internacionais, espere que isso leve de quatro a dez vezes mais. Uma maneira de limitar o tempo necessário é pegar um arquivo de https://download.freebsd.org/ftp/development/subversion/[seed]. Ele é grande (~1GB), mas consome menos tráfego de rede e leva menos tempo para baixar do que o svnsync. Extraia o arquivo e o atualize: [source,shell] .... % tar xf svnmirror-base-r261170.tar.xz % svnsync sync file:///home/svnmirror/base .... Agora, configure isso para executar a partir do man:cron[8], faça checkouts localmente, configure um servidor svnserve para as máquinas locais com as quais conversar, etc. O mirror seed está definido para buscar o conteúdo a partir de `svn://svn.freebsd.org/base`. A configuração para o mirror é armazenada em `revprop 0` no mirror local. Para ver a configuração, tente: [source,shell] .... % svn proplist -v --revprop -r 0 file:///home/svnmirror/base .... Use `svn propset` para mudar as coisas. [[svn-advanced-use-committing-high-ascii-data]] ==== Fazendo commit de dados High ASCII Os arquivos que possuem bits high-ASCII são considerados arquivos binários no `SVN`, portanto, as verificações de pré-commit falham e indicam que a propriedade `mime-type` deve ser definida como `application/octet-stream`. No entanto, o uso deste é desencorajado, por isso, não o defina. A melhor maneira é sempre evitar dados high-ASCII, para que possam ser lidos em qualquer lugar com qualquer editor de texto, mas se não for possivel evitar, em vez de alterar o mime-type, defina a propriedade `fbsd:notbinary` com o `propset`: [source,shell] .... % svn propset fbsd:notbinary yes foo.data .... [[svn-advanced-use-maintaining-a-project-branch]] ==== Mantendo um branch de projeto Uma branch de projeto é aquela que está sincronizada com o head (ou outra branch) e é usada para desenvolver um projeto e, em seguida, fazer o seu commit de volta para o head. No `SVN`, o branch "dolphin" é usado para isso. Uma branch "dolphin" é aquela que diverge por um tempo e é finalmente enviada de volta ao branch original. Durante a migração do código de desenvolvimento em uma direção (do head para o branch apenas). Não é feito o commit de nenhum código de volta ao head até o final. Depois que é feito o commit da branch no final, ela estará morta (embora uma nova branch com o mesmo nome possa ser criada depois que a que está morta é excluída). Como explicado em https://people.FreeBSD.org/\~peter/svn_notes.txt[https://people.FreeBSD.org/~peter/svn_notes.txt], o trabalho que destina-se a ser mesclado de volta para o HEAD deve estar em [.filename]#base/projects/#. Se o trabalho é benéfico para a comunidade do FreeBSD de alguma forma, mas não se destina a ser mesclado diretamente no HEAD, então o local apropriado é [.filename]#base/user/username/#. https://svnweb.freebsd.org/base/projects/GUIDELINES.txt[Esta página] contém mais detalhes. Para criar um branch de projeto: [source,shell] .... % svn copy svn+ssh://repo.freebsd.org/base/head svn+ssh://repo.freebsd.org/base/projects/spif .... Para mesclar as alterações do HEAD de volta ao branch de projeto: [source,shell] .... % cd copy_of_spif % svn merge svn+ssh://repo.freebsd.org/base/head % svn commit .... É importante resolver quaisquer conflitos de mesclagem antes de fazer o commit. === Algumas dicas Nos logs de commit, etc., "rev 179872" é soletrado "r179872" conforme a convenção. É possível acelerar o svn adicionando estas entradas ao [.filename]#~/.ssh/config#: [source,shell] .... Host * ControlPath ~/.ssh/sockets/master-l-r@h:p ControlMaster auto ControlPersist yes .... e depois digitando [source,shell] .... mkdir ~/.ssh/sockets .... Fazer o check-out de uma cópia de trabalho com um cliente Subversion padrão sem patches específicos do FreeBSD (`OPTIONS_SET=FREEBSD_TEMPLATE`) significará que as tags `$FreeBSD: head/pt_BR.ISO8859-1/articles/committers-guide/article.xml 53731 2020-01-01 14:37:53Z ebrandi $` não serão expandidas. Uma vez que a versão correta foi instalada, engane o Subversion para expandi-las da seguinte forma: [source,shell] .... % svn propdel -R svn:keywords . % svn revert -R . .... Isso eliminará os patches para os quais ainda não foi feito o commit. É possível preencher automaticamente os campos de log de commit "Sponsored by" e "MFC after" configurando os campos "freebsd-sponsored-by" e "freebsd-mfc-after" na seção "[miscellany]" do arquivo de configuração [.filename]#~/.subversion/config#. Por exemplo: [.programlisting] .... freebsd-sponsored-by = The FreeBSD Foundation freebsd-mfc-after = 2 weeks .... [[conventions]] == Configuração, Convenções e Tradições Existe uma série de coisas para fazer como um novo desenvolvedor. O primeiro conjunto de etapas é específico apenas para os committers. Essas etapas devem ser feitas por um mentor para aqueles que não são committers. [[conventions-committers]] === Para novos committers Aqueles que receberam direitos de commit para os repositórios do FreeBSD devem seguir estes passos. * Obtenha a aprovação do seu mentor antes de fazer o commit de cada uma dessas mudanças! * Os arquivos [.filename]#.ent# e [.filename]#.xml# mencionados abaixo existem no repositório SVN do Projeto de Documentation do FreeBSD em `svn+ssh://repo.FreeBSD.org/doc/`. * Novos arquivos que não possuem a propriedade `FreeBSD=%H svn:keywords` serão rejeitados quando você tentar fazer o commit dos mesmos para o repositório. Certifique-se de ler <> sobre como adicionar e remover arquivos. Verifique se o [.filename]#~/.subversion/config# contém as entradas necessárias de "auto-props" do [.filename]#auto-props.txt# mencionado lá. * Todos os commits do [.filename]#src# vão para o FreeBSD-CURRENT antes de serem mesclados para o FreeBSD-STABLE. A branch do FreeBSD-STABLE deve manter a compatibilidade de ABI e de API com as versões anteriores dessa branch. Não mescle as alterações que quebram essa compatibilidade. [[commit-steps]] [.procedure] .Procedure: Etapas para os novos committers . Adicione uma entidade de autor + [.filename]#doc/head/shared/xml/authors.ent# - Adicione uma entidade de autor. Etapas posteriores dependem dessa entidade, e a falta dessa etapa fará com que a compilação do [.filename]#doc/# falhe. Essa é uma tarefa relativamente fácil, mas continua sendo um bom primeiro teste de habilidades no controle de versão. . Atualize a lista de desenvolvedores e colaboradores + [.filename]#doc/head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml# - Adicione uma entrada à seção "Desenvolvedores" da link:{contributors}#staff-committers[Lista de Contribuidores]. As entradas são classificadas pelo sobrenome. + [.filename]#doc/head/en_US.ISO8859-1/articles/contributors/contrib.additional.xml# - _Remova_ a entrada da seção "Contribuidores Adicionais". As entradas são classificadas pelo primeiro nome. . Adicione um item de notícias + [.filename]#doc/head/shared/xml/news.xml# - Adicione uma entrada. Procure por outras entradas que anunciam novos committers e siga o formato. Use a data do email de aprovação do mailto:core@FreeBSD.org[core@FreeBSD.org] para o commit bit. . Adicione uma chave PGP + [.filename]#doc/head/shared/pgpkeys/pgpkeys.ent# e [.filename]#doc/head/shared/pgpkeys/pgpkeys-developers.xml# - Adicione a sua chave PGP ou GnuPG. Aqueles que ainda não têm uma chave devem ver <>. + O Dag-Erling Smørgrav mailto:des@FreeBSD.org[des@FreeBSD.org] escreveu um script de shell ([.filename]#doc/head/shared/pgpkeys/addkey.sh#) para tornar isto mais fácil. Consulte o arquivo http://svnweb.FreeBSD.org/doc/head/shared/pgpkeys/README[README] para obter mais informações. + Use o [.filename]#doc/head/shared/pgpkeys/checkkey.sh# para verificar se as chaves atendem aos padrões mínimos das boas práticas recomendadas. + Depois de adicionar e verificar uma chave, adicione os dois arquivos atualizados ao controle de versão do código fonte, e em seguida faça o commit. As entradas neste arquivo são classificadas pelo sobrenome. + [NOTE] ==== É muito importante ter uma chave PGP/GnuPG atualizada no repositório. A chave pode ser necessária para a identificação positiva de um committer. Por exemplo, os Administradores do FreeBSD mailto:admins@FreeBSD.org[admins@FreeBSD.org]podem precisar dela para a recuperação da conta. Um chaveiro completo dos usuários do `FreeBSD.org` está disponível para download em https://www.FreeBSD.org/doc/pgpkeyring.txt[https://www.FreeBSD.org/doc/pgpkeyring.txt]. ==== . Atualize as informações do Mentor e do Mentee + [.filename]#base/head/shared/misc/committers-repository.dot# - Adicione uma entrada à seção committers atuais, onde _repository_ é `doc`, `ports`, ou `src`, dependendo dos privilégios de commit concedidos. + Adicione uma entrada para cada relacionamento adicional de mentor/mentee na seção inferior. . Gere uma senha do Kerberos + Veja <> para gerar ou definir um Kerberos para uso com outros serviços do FreeBSD, como o banco de dados de rastreamento de bugs. . Opcional: Ative a sua conta na Wiki + https://wiki.freebsd.org[Conta no Wiki do FreeBSD] - Uma conta no wiki permite que compartilhe projetos e ideias. Aqueles que ainda não têm uma conta podem seguir as instruções da https://wiki.freebsd.org/AboutWiki[Página Sobre a Wiki] para obter uma. Entre em contato com mailto:wikiadmin@FreeBSD.org[wikiadmin@FreeBSD.org] se precisar de ajuda com sua conta no Wiki. . Opcional: Atualize informações do Wiki + Informações do Wiki - Depois de obter acesso ao wiki, algumas pessoas adicionam entradas nas páginas https://wiki.freebsd.org/HowWeGotHere[How We Got Here], https://wiki.freebsd.org/IRC/Nicknames[IRC Nicks] e https://wiki.freebsd.org/Community/Dogs[Dogs of FreeBSD] páginas. . Opcional: Atualize o Ports com as suas Informações Pessoais + [.filename]#ports/astro/xearth/files/freebsd.committers.markers# e [.filename]#src/usr.bin/calendar/calendars/calendar.freebsd# - Algumas pessoas adicionam entradas para elas nestes arquivos para mostrar onde estão localizadas ou a data de seu aniversário. . Opcional: Evite Correspondências Duplicadas + Assinantes das listas http://lists.FreeBSD.org/mailman/listinfo/svn-src-all[svn-src-all], http://lists.FreeBSD.org/mailman/listinfo/svn-ports-all[svn-ports-all] ou da http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all[svn-doc-all] podem desejar cancelar a assinatura para evitar receber cópias duplicadas de mensagens de commit e de followups. [[conventions-everyone]] === Para todos [[conventions-everyone-steps]] [.procedure] . Apresente-se aos outros desenvolvedores, caso contrário, ninguém fará a menor ideia de quem você é ou no que você está trabalhando. A introdução não precisa ser uma biografia abrangente, basta escrever um parágrafo ou dois sobre quem você é, em que você planeja trabalhar como desenvolvedor no FreeBSD e quem será seu mentor. Envie os parágrafos por e-mail para a lista de discussão dos desenvolvedores do FreeBSD e você estará a caminho! . Entre na `freefall.FreeBSD.org` e crie um arquivo [.filename]#/var/forward/user# (no qual _user_ é seu nome de usuário) contendo o endereço de e-mail para o qual você deseja que o correio endereçado para _yourusername_@FreeBSD.org seja encaminhado. Isto inclui todas as mensagens de commit assim como qualquer outro email endereçado à lista de discussão dos committers do FreeBSD e à lista de discussão dos desenvolvedores do FreeBSD. Caixas de correio realmente grandes que tenham residência permanente na `freefall` podem ser truncadas sem aviso se o espaço precisar ser liberado, então encaminhe suas mensagens ou salve-as em outro lugar. + [NOTE] ==== Se o seu sistema de e-mail usa SPF com regras estritas, você deve colocar o host `mx2.FreeBSD.org` na whitelist de verificações do SPF. ==== + Devido ao load severo imposto aos servidores centrais que fazem o processamento da lista de discussão devido ao grande volume de SPAMs, o servidor de front-end faz algumas verificações básicas e descarta algumas mensagens com base nessas verificações. No momento, as informações de DNS adequadas para o host de conexão são a única verificação ativa, mas isso pode mudar. Algumas pessoas culpam estas verificações por rejeitar e-mails válidos. Para que essas verificações sejam desativadas no seu email, crie um arquivo chamado [.filename]#~/.spam_lover# no servidor `freefall.FreeBSD.org`. [NOTE] ==== Aqueles que são desenvolvedores, mas não são committers, não serão inscritos nas listas de discussão de desenvolvedores ou de committers. As assinaturas são derivadas dos direitos de acesso. ==== [[smtp-setup]] ==== Configuração de acesso SMTP Para aqueles dispostos a enviar mensagens de e-mail através da infraestrutura do FreeBSD.org, siga as instruções abaixo: [.procedure] . Aponte seu cliente de e-mail para `smtp.FreeBSD.org:587`. . Habilite o STARTTLS. . Assegure-se de que seu endereço `From:` esteja configurado para `_yourusername_@FreeBSD.org`. . Para autenticação, você pode usar o seu nome de usuário e a sua senha do Kerberos no cluster do FreeBSD (veja <>). O principal `_yourusername_/mail` é o preferido, pois é válido apenas para autenticação dos recursos de correio. + [NOTE] ==== Não inclua `@FreeBSD.org` ao digitar seu nome de usuário. ==== .Notas Adicionais [NOTE] ==== * Aceitará apenas mensagens de `_yourusername_@FreeBSD.org`. Se você for autenticado como um usuário, não terá permissão para enviar e-mails como outro. * Um cabeçalho será anexado com o nome de usuário do SASL: (`Authenticated sender: _username_`). * O host possui vários limites de taxa para reduzir as tentativas de força bruta. ==== [[smtp-setup-local-mta]] ===== Usando um MTA Local para Encaminhar Emails para o Serviço SMTP do FreeBSD.org Também é possível usar um MTA local para encaminhar emails enviados localmente para os servidores SMTP do FreeBSD.org. [[smtp-setup-local-postfix]] .Usando o Postfix [example] ==== Para dizer a uma instância local do Postfix que qualquer email de `_yourusername_@FreeBSD.org` deve ser encaminhado para os servidores do FreeBSD.org, adicione isto ao seu [.filename]#main.cf#: [.programlisting] .... sender_dependent_relayhost_maps = hash:/usr/local/etc/postfix/relayhost_maps smtp_sasl_auth_enable = yes smtp_sasl_security_options = noanonymous smtp_sasl_password_maps = hash:/usr/local/etc/postfix/sasl_passwd smtp_use_tls = yes .... Crie [.filename]#/usr/local/etc/postfix/relayhost_maps# com o seguinte conteúdo: [.programlisting] .... yourusername@FreeBSD.org [smtp.freebsd.org]:587 .... Crie [.filename]#/usr/local/etc/postfix/sasl_passwd# com o seguinte conteúdo: [.programlisting] .... [smtp.freebsd.org]:587 yourusername:yourpassword .... Se o servidor de email for usado por outras pessoas, talvez você queira impedir que elas enviem emails do seu endereço. Para configurar isso, adicione estas entradas ao seu [.filename]#main.cf#: [.programlisting] .... smtpd_sender_login_maps = hash:/usr/local/etc/postfix/sender_login_maps smtpd_sender_restrictions = reject_known_sender_login_mismatch .... Crie [.filename]#/usr/local/etc/postfix/sender_login_maps# com o seguinte conteúdo: [.programlisting] .... yourusername@FreeBSD.org yourlocalusername .... Onde _yourlocalusername_ é o usuário SASL utilizado para conectar na instância local do Postfix. ==== [[mentors]] === Mentores Todos os novos desenvolvedores têm um mentor atribuído a eles nos primeiros meses. Um mentor é responsável por ensinar ao aprendiz as regras e convenções do projeto e orientar seus primeiros passos na comunidade de desenvolvedores. O mentor também é pessoalmente responsável pelas ações do aprendiz durante este período inicial. Para committers: não faça nenhum commit sem antes obter a aprovação do seu mentor. Documente essa aprovação com uma linha `Approved by:` na mensagem de commit. Quando o mentor decide que um aprendiz já aprendeu o necessário e está pronto para fazer commits por conta própria, o mentor anuncia o fato com um commit no [.filename]#conf/mentors#. Este arquivo está na branch [.filename]#svnadmin# de cada repositório: [.informaltable] [cols="1,1", frame="none"] |=== |`src` |[.filename]#base/svnadmin/conf/mentors# |`doc` |[.filename]#doc/svnadmin/conf/mentors# |`ports` |[.filename]#ports/svnadmin/conf/mentors# |=== [NOTE] ==== Os novos committers devem ter como objetivo realizar commits o suficiente para que seu mentor se sinta confortável em liberá-los da mentoria no primeiro ano. Se eles ainda estiverem sob orientação, o corpo gerencial apropriado (core, doceng ou portmgr) deve tentar garantir que não haja barreiras que impeçam a conclusão. Se o committer não for capaz de satisfazer seu mentor de prontidão por um ano e meio, seu commit bit pode ser convertido para membro do projeto. ==== [[pre-commit-review]] == Revisão pré-commit A revisão de código é uma maneira de aumentar a qualidade do software. As seguintes diretrizes se aplicam a commits na ramificação `head` (-CURRENT) do repositório `src`. Outras ramificações e as árvores do `ports` e do `docs` têm suas próprias políticas de revisão, mas essas diretrizes geralmente se aplicam a commits que exigem revisão: * Todas as alterações não triviais devem ser revisadas antes de serem cometidas no repositório. * As revisões podem ser conduzidas por e-mail, pelo Bugzilla, pelo Phabricator ou por outro mecanismo. Sempre que possível, as revisões devem ser públicas. * O desenvolvedor responsável por uma mudança de código também é responsável por fazer todas as alterações necessárias relacionadas à revisão. * A revisão de código pode ser um processo iterativo, que continua até que o patch esteja pronto para o commit. Especificamente, uma vez que um patch é enviado para revisão, ele deve receber um explícito "looks good" antes que o commit possa ser feito. Desde que a aprovação seja explícita, ela pode ser formalizada de qualquer forma que faça sentido para o método de revisão. * Timeouts não são um substituto para revisão. Às vezes, as revisões de código demoram mais tempo do que você esperaria, especialmente para recursos maiores. As formas aceitas de acelerar os tempos de revisão dos seus patches são: * Revise os patches de outras pessoas. Se você ajudar, todos estarão mais dispostos a fazer o mesmo por você; A boa vontade é a nossa moeda. * Ping o patch. Se for urgente, forneça as razões pelas quais é importante para você finalizá-lo e faça o ping a cada dois dias. Se não for urgente, a frequência adequada de ping é de uma vez por semana. Lembre-se de que você está pedindo um tempo valioso de outros desenvolvedores profissionais. * Peça ajuda em listas de discussão, IRC, etc. Outros podem ajudá-lo diretamente ou sugerir um revisor. * Dividir seu patch em vários patches pequenos os quais se aplicam uns sobre os outros. Quanto menor o seu patch, maior a probabilidade de alguém dar uma rápida olhada nele. + Ao fazer grandes mudanças, é útil ter isso em mente desde o início do esforço, pois quebrar grandes alterações em pequenas é geralmente difícil depois que estão prontas. Os desenvolvedores devem participar de revisões de código fazendo revisões e recebendo revisões. Se alguém tiver a gentileza de revisar seu código, você deve devolver o favor a outra pessoa. Observe que, embora qualquer pessoa seja bem-vinda para revisar e dar feedback sobre um patch, apenas um especialista no assunto apropriado pode aprovar uma alteração. Geralmente, este especialista será um committer que trabalha com o código em questão regularmente. Em alguns casos, nenhum especialista no assunto pode estar disponível. Nesses casos, uma revisão por um desenvolvedor experiente é suficiente quando associada a testes apropriados. [[commit-log-message]] == Mensagens de Log de Commit Esta seção contém algumas sugestões e tradições de como os logs de commit são formatados. Além de incluir uma mensagem informativa com cada commit, algumas informações adicionais podem ser necessárias. Essas informações consistem em uma ou mais linhas contendo a palavra-chave ou frase, dois-pontos, guias para formatação e, em seguida, as informações adicionais. As palavras ou frases-chave são: [.informaltable] [cols="20%,80%", frame="none"] |=== |`PR:` |O relatório do problema (se houver) que é afetado (normalmente, por estar fechado) por este commit. Vários PRs podem ser especificados em uma linha, separados por vírgulas ou espaços. |`Submitted by:` | O nome e o endereço de e-mail da pessoa que enviou a correção; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD. Se o requisitante for o mantenedor do port que está sendo atualizado pelo commit, inclua "(maintainer)" após o endereço de e-mail. Evite ofuscar o endereço de e-mail do remetente, pois isso adiciona trabalho adicional ao pesquisar os registros. |`Reviewed by:` |O nome e o endereço de e-mail da pessoa ou pessoas que revisaram a alteração; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD. Se um patch foi submetido a uma lista de discussão para revisão e a revisão foi favorável, basta incluir o nome da lista. |`Approved by:` a| O nome e endereço de e-mail da pessoa ou pessoas que aprovaram a alteração; para desenvolvedores, apenas o nome de usuário no cluster do FreeBSD. É costume obter aprovação prévia para um commit se for para uma área da árvore na qual você normalmente não faz commit. Além disso, durante a preparação para uma nova versão, todos os commits _devem_ ser aprovados pela equipe de engenharia de release. Enquanto estiver sob orientação, obtenha aprovação do mentor antes do commit. Digite o nome de usuário do mentor neste campo e adicione uma nota de que ele é um mentor: [source,shell] .... Approved by: username-of-mentor (mentor) .... Se uma equipe aprovou esses commits, inclua o nome da equipe seguido do nome de usuário do aprovador entre parênteses. Por exemplo: [source,shell] .... Approved by: re (username) .... |`Obtained from:` |O nome do projeto (se houver) do qual o código foi obtido. Não use esta linha para o nome de uma pessoa individual. |`Sponsored by:` |Organizações patrocinadoras dessa mudança, se houver. Separe várias organizações com vírgulas. Se apenas uma parte do trabalho foi patrocinada, ou diferentes montantes de patrocínio foram fornecidos a diferentes autores, por favor, forneça os devidos créditos entre parênteses após cada nome de patrocinador. Por exemplo, `Example.com (alice, refatoração de código), Wormulon (bob), Momcorp (cindy)` mostra que Alice foi patrocinada pela Example.com para refatoração de código, enquanto Wormulon patrocinou o trabalho de Bob e a Momcorp patrocinou o trabalho de Cindy. Outros autores não foram patrocinados ou optaram por não listar o patrocínio. |`MFC after:` |Para receber um lembrete por e-mail para o MFC em uma data posterior, especifique o número de dias, semanas ou meses após os quais um MFC está planejado. |`MFC to:` |Se o commit deve ser mesclado em um subconjunto de branches estáveis, especifique os nomes das branchs. |`MFC with:` |Se o commit deve ser mesclado junto com um commit anterior em um único MFC (por exemplo, onde o commit corrige um bug da alteração anterior), especifique o número de revisão correspondente. |`Relnotes:` |Se a alteração for candidata a inclusão nas notas de lançamento da próxima versão da branch, defina como `yes`. |`Security:` |Se a alteração estiver relacionada a uma vulnerabilidade de segurança ou exposição de segurança, inclua uma ou mais referências ou uma descrição do problema. Se possível, inclua um URL VuXML ou um ID CVE. |`Evento:` |Descrição para o evento em que essa confirmação foi feita. Se este for um evento recorrente, adicione o ano ou até mesmo o mês. Por exemplo, isso pode ser `FooBSDcon 2019`. A idéia por trás dessa linha é dar reconhecimento a conferências, reuniões e outros tipos de reuniões e mostrar que elas são úteis. Por favor, não use a linha `Patrocinado por:` para isso, pois isso significa que as organizações patrocinam determinados recursos ou desenvolvedores que trabalham neles. |`Differential Revision:` |A URL completa da revisão do Phabricator. Esta linha __ deve ser a última linha __. Por exemplo: `https://reviews.freebsd.org/D1708`. |=== .Commit Log para um commit baseado em um PR [example] ==== O commit é baseado em um patch de um PR enviado por John Smith. Os campos da mensagem de commit "PR" e "Submitted by" são preenchidos. [.programlisting] .... ... PR: 12345 Submitted by: John Smith .... ==== .Commit log de um commit que precisa de revisão [example] ==== O sistema de memória virtual está sendo alterado. Depois de enviar os patches para a lista de discussão apropriada (neste caso, `freebsd-arch`) e as mudanças foram aprovadas. [.programlisting] .... ... Reviewed by: -arch .... ==== .Commit log de um commit que precisa de aprovação [example] ==== Commit um port, depois de trabalhar com o MAINTAINER, que disse para ir em frente e executar o commit. [.programlisting] .... ... Approved by: abc (maintainer) .... No qual o _abc_ é o nome da conta da pessoa que aprovou. ==== .Commit log de um commit que importa código do OpenBSD [example] ==== Efetuando o commit de códigos baseados no trabalho feito no projeto OpenBSD. [.programlisting] .... ... Obtained from: OpenBSD .... ==== .Commit Log para uma mudança no FreeBSD-CURRENT com um commit planejado para o FreeBSD-STABLE para seguir em uma data posterior. [example] ==== Efetuando o commit de códigos que serão mesclados do FreeBSD-CURRENT na branch do FreeBSD-STABLE após duas semanas. [.programlisting] .... ... MFC after: 2 weeks .... Onde _2_ é o número de dias, semanas ou meses após o qual um MFC é planejado. A opção _weeks_ pode ser `day`, `dias`, `semana`, `semanas`, `mês`, `meses`. ==== Muitas vezes é necessário combinar isso. Considere a situação em que um usuário enviou um código contendo o PR do projeto NetBSD. Olhando para o PR, o desenvolvedor vê que não é uma área da árvore na qual eles normalmente trabalham, então eles têm a mudança revisada pela lista de discussão `arch`. Como a mudança é complexa, o desenvolvedor opta pelo MFC após um mês para permitir testes adequados. A informação extra para incluir no commit seria algo como .Exemplo de log de commit combinado [example] ==== [.programlisting] .... PR: 54321 Submitted by: John Smith Reviewed by: -arch Obtained from: NetBSD MFC after: 1 month Relnotes: yes .... ==== [[pref-license]] == Licença preferida para novos arquivos A política de licença completa do Projeto FreeBSD pode ser encontrada em https://www.FreeBSD.org/internal/software-license/[https://www.FreeBSD.org/internal/software-license/]. O restante desta seção destina-se a ajudá-lo a começar. Por via de regra, quando em dúvida, pergunte. É muito mais fácil dar conselhos do que consertar a árvore de código fonte. O Projeto FreeBSD sugere e usa este texto como o esquema de licença preferencial: [.programlisting] .... /*- * SPDX-License-Identifier: BSD-2-Clause-FreeBSD * * Copyright (c) [year] [your name] * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions and the following disclaimer. * 2. Redistributions in binary form must reproduce the above copyright * notice, this list of conditions and the following disclaimer in the * documentation and/or other materials provided with the distribution. * * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF * SUCH DAMAGE. * * [id for your version control system, if any] */ .... O projeto FreeBSD desencoraja fortemente a chamada "cláusula publicitária" no novo código. Devido ao grande número de contribuidores para o projeto FreeBSD, o cumprimento desta cláusula para muitos fornecedores comerciais se tornou difícil. Se você tiver um código na árvore com a cláusula de publicidade, considere removê-lo. Na verdade, considere usar a licença acima para o seu código. O projeto FreeBSD desencoraja completamente novas licenças e variações nas licenças padrões. Novas licenças requerem a aprovação do Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] para residir no repositório principal. Quanto mais licenças diferentes forem usadas na árvore, mais problemas isso causará para aqueles que desejarem utilizar esse código, geralmente de consequências não intencionais de uma licença mal formulada. A política do projeto determina que o código sob algumas licenças não-BSD deve ser colocado apenas em seções específicas do repositório e, em alguns casos, a compilação deve ser condicional ou até mesmo desativada por padrão. Por exemplo, o kernel GENERIC deve ser compilado apenas sob licenças idênticas ou substancialmente semelhantes à licença BSD. O software licenciado GPL, APSL, CDDL, etc, não deve ser compilado no GENERIC. Os desenvolvedores são lembrados de que, em código aberto, ficar "aberto" corretamente é tão importante quanto obter o "fonte" correto, já que o manuseio inadequado da propriedade intelectual tem sérias consequências. Quaisquer dúvidas ou preocupações devem imediatamente ser levadas à atenção do Core Team. [[tracking.license.grants]] == Acompanhando as Licenças Concedidas ao Projeto FreeBSD Vários softwares ou dados existem nos repositórios onde o projeto FreeBSD recebeu uma licença especial para poder usá-los. Um caso em questão são as fontes do Terminus para uso com o man:vt[4]. Aqui, o autor Dimitar Zhekov nos permitiu usar a fonte "Terminus BSD Console" sob uma licença BSD de 2 cláusulas, em vez da licença Open Font License que ele normalmente usa. É claramente sensível manter um registro de tais concessões de licença. Para esse fim, o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] decidiu manter um arquivo delas. Sempre que o projeto FreeBSD receber uma licença especial, nós exigimos que o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] seja notificado. Qualquer desenvolvedor envolvido na obtenção de tal concessão de licença, por favor envie os detalhes para o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] incluindo: * Detalhes de contato para as pessoas ou organizações que concederam a licença especial. * Quais arquivos, diretórios etc. nos repositórios são cobertos pela concessão da licença, incluindo os números de revisão dos commits nos quais qualquer material especialmente licenciado tenha sido incorporado. * A data em que a licença entra em vigor. Salvo acordo em contrário, esta será a data em que a licença foi emitida pelos autores do software em questão. * O texto da licença. * Uma nota de quaisquer restrições, limitações ou exceções que se aplicam especificamente ao uso do material licenciado pelo FreeBSD. * Qualquer outra informação relevante. Uma vez que o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] esteja satisfeito de que todos os detalhes necessários foram reunidos e estão corretos, o secretário enviará um aviso de recebimento assinado com o PGP, incluindo os detalhes da licença. Esse recibo será persistentemente arquivado e servirá como nosso registro permanente da concessão da licença. O arquivo de licença deve conter apenas detalhes das concessões de licença; este não é o lugar para qualquer discussão em torno de licenciamento ou outros assuntos. O acesso aos dados dentro do arquivo de licença estará disponível mediante solicitação para o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org]. [[developer.relations]] == Relações entre os Desenvolvedores Ao trabalhar diretamente em seu próprio código ou em um código que já esteja bem estabelecido como sua responsabilidade, provavelmente haverá pouca necessidade de verificar com outros committers antes de entrar com um commit. Ao trabalhar em um bug em uma área do sistema que é claramente órfã (e existem algumas dessas áreas, para nossa vergonha), o mesmo se aplica. Ao modificar partes do sistema que são mantidas, formalmente ou informalmente, considere solicitar uma revisão exatamente como um desenvolvedor teria de fazer antes de se tornar um committer. Para os ports, entre em contato com o `MAINTAINER` listado no [.filename]#Makefile#. Para determinar se uma área da árvore é mantida, verifique o arquivo MAINTAINERS na raiz da árvore. Se ninguém estiver listado, analise o histórico de revisões para ver quem fez o commit de alterações no passado. Um script de exemplo que lista cada pessoa que já fez commit de um determinado arquivo junto com o número de commits que cada pessoa fez pode ser encontrado na `freefall` em [.filename]#~eadler/bin/whodid#. Se as consultas não forem atendidas ou se o committer indicar uma falta de interesse na área afetada, vá em frente e faça o commit. [IMPORTANT] ==== Evite enviar e-mails privados para os mantenedores. Outras pessoas podem estar interessadas na conversa, não apenas no resultado final. ==== Se houver qualquer dúvida sobre um commit por qualquer razão, submeta-o ao processo de revisão antes de faze-lo. É melhor fazer com que ele seja criticado lá e não quando ele já fizer parte do repositório. Se um commit resulta em controvérsia, pode ser aconselhável considerar a possibilidade de fazer o rollback do commit até que o assunto seja resolvido. Lembre-se, com um sistema de controle de versão, podemos sempre alterá-lo de volta. Não impugne as intenções dos outros. Se eles vêem uma solução diferente para um problema, ou até um problema diferente, provavelmente não é porque eles são estúpidos, porque eles têm parentesco questionável, ou porque eles estão tentando destruir o trabalho duro, a imagem pessoal ou o FreeBSD, mas basicamente porque eles têm uma visão diferente do mundo. Diferente é bom. Discorde honestamente. Argumente sua posição com base em seus méritos, seja honesto quanto a quaisquer deficiências que possa ter, e esteja aberto para ver a solução deles, ou mesmo a visão deles do problema, com uma mente aberta. Aceite a correção. Somos todos falíveis. Quando você cometer um erro, peça desculpas e continue com a vida. Não se bata, e certamente não espanque os outros por seu erro. Não perca tempo com constrangimentos ou recriminações, apenas conserte o problema e siga em frente. Peça por ajuda. Procure (e dê) revisões dos seus pares. Uma das maneiras pelas quais o software de código aberto deve se sobressair é no número de globos oculares aplicados a ele; isso não se aplica se ninguém revisar o código. [[if-in-doubt]] == Se em dúvida... Quando não tiver certeza sobre algo, seja um problema técnico ou uma convenção do projeto, não se esqueça de perguntar. Se você ficar em silêncio, nunca fará progressos. Se estiver relacionado a um problema técnico, pergunte nas listas públicas de discussão. Evite a tentação de enviar e-mail para a pessoa que conhece a resposta. Dessa forma, todos poderão aprender com a pergunta e a resposta. Para perguntas específicas ou administrativas do projeto, pergunte na seguinte ordem: * Seu mentor ou ex-mentor. * Um committer experiente no IRC, email, etc. * Qualquer equipe com um "hat" (chapéu), uma vez que eles podem lhe dar uma resposta definitiva. * Se ainda não tiver certeza, pergunte na lista de discussão dos desenvolvedores do FreeBSD. Uma vez que sua pergunta seja respondida, se ninguém lhe indicou a documentação que soletra a resposta para sua pergunta, documente-a, pois outros terão a mesma pergunta no futuro. [[bugzilla]] == Bugzilla O Projeto FreeBSD utiliza o Bugzilla para rastrear bugs e requisições de alteração. Certifique-se de fechar o PR caso você faça o commit de uma correção ou sugestão encontrada no banco de dados de PR. Também é considerada uma boa prática você reservar um tempo para fechar qualquer PR associado aos seus commits, se apropriado. Committers com contas não-``FreeBSD.org`` no Bugzilla podem ter a conta antiga mesclada com a conta `FreeBSD.org` seguindo estes passos: [.procedure] . Faça o login usando sua conta antiga. . Abra um novo bug. Escolha `Services` como o Produto e `Bug Tracker` como o Componente. Na descrição de erros liste as contas que você deseja mesclar. . Faça o login usando a conta do `FreeBSD.org` e poste um comentário no bug recém-aberto para confirmar a propriedade. Veja <> para mais detalhes sobre como gerar ou definir uma senha para sua conta `FreeBSD.org`. . Se houver mais de duas contas para mesclar, poste comentários de cada uma delas. Você pode descobrir mais sobre o Bugzilla em: * * https://www.FreeBSD.org/support/[https://www.FreeBSD.org/support/] [[phabricator]] == Phabricator O projeto FreeBSD utiliza o https://reviews.freebsd.org[Phabricator] para solicitações de revisão de código. Veja a página https://wiki.freebsd.org/CodeReview[CodeReview] no wiki para detalhes. Committers com contas não-`FreeBSD.org` no Phabricator podem ter a conta antiga renomeada para a conta `FreeBSD.org` seguindo estes passos: [.procedure] . Altere o email da conta do Phabricator para o seu email `FreeBSD.org`. . Abra um novo bug em nosso bug tracker usando sua conta `FreeBSD.org`, veja <> para mais informações. Escolha `Services` como o Produto e `Code Review` como o Componente. Na descrição de bugs, solicite que a sua conta do Phabricator seja renomeada e forneça um link para o usuário do Phabricator. Por exemplo, `https://reviews.freebsd.org/p/bob_example.com/` [IMPORTANT] ==== As contas do Phabricator não podem ser mescladas, por favor, não abra uma nova conta. ==== [[people]] == Quem é quem Além dos repositórios meisters, existem outros membros e equipes do projeto FreeBSD que você provavelmente conhecerá no exercício da sua função como committer. Resumidamente, e de forma alguma inclusivamente, estes são: Equipe de Engenharia de Documentação mailto:doceng@FreeBSD.org[doceng@FreeBSD.org]:: O doceng é o grupo responsável pela infraestrutura de criação de documentação, aprovando de novos committers de documentação e garantindo que o website do FreeBSD e a documentação no site FTP estão atualizados em relação à árvore subversion. Não é um corpo de resolução de conflitos. A grande maioria das discussões relacionadas à documentação ocorre na http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc[lista de discussão do projeto de documentação do FreeBSD]. Mais detalhes sobre a equipe doceng podem ser encontrados em seu https://www.FreeBSD.org/internal/doceng/[charter]. Os committers interessados em contribuir com a documentação devem se familiarizar com o link:{fdp-primer}[Primer do Projeto de Documentação]. Glen Barber mailto:gjb@FreeBSD.org[gjb@FreeBSD.org], Konstantin Belousov mailto:kib@FreeBSD.org[kib@FreeBSD.org], Bryan Drewery mailto:[bdrewery@FreeBSD.org], Marc Fonvieille mailto:blackend@FreeBSD.org[blackend@FreeBSD.org], Xin Li mailto:delphij@FreeBSD.org[delphij@FreeBSD.org], Colin Percival mailto:cperciva@FreeBSD.org[cperciva@FreeBSD.org] Hiroki Sato mailto:hrs@FreeBSD.org[hrs@FreeBSD.org], Gleb Smirnoff mailto:glebius@FreeBSD.org[glebius@FreeBSD.org]:: Estes são os membros da Equipe de Engenharia de Release mailto:re@FreeBSD.org[re@FreeBSD.org]. Essa equipe é responsável por definir os prazos de lançamento e por controlar o processo de release. Durante o congelamento de código, os engenheiros de release têm autoridade final sobre todas as alterações no sistema para qualquer branch que esteja com status de release pendente. Se há algo que você deseja mesclar do FreeBSD-CURRENT para o FreeBSD-STABLE (quaisquer valores que eles possam ter em um dado momento), estas são as pessoas com quem conversar sobre isso. Gordon Tetlow mailto:gordon@FreeBSD.org[gordon@FreeBSD.org]:: Gordon Tetlow é o https://www.FreeBSD.org/security/[Oficial de Segurança do FreeBSD] e supervisiona a Equipe Oficial de Segurança mailto:security-officer@FreeBSD.org[security-officer@FreeBSD.org]. Garrett Wollman mailto:wollman@FreeBSD.org[wollman@FreeBSD.org]:: Se você precisar de conselhos sobre aspectos internos obscuros da rede ou não tiver certeza de alguma mudança potencial no subsistema de rede que você tem em mente, Garrett é alguém com quem conversar. Garrett também é muito conhecedor dos vários padrões aplicáveis ao FreeBSD. Lista de discussão dos committers do FreeBSD:: http://lists.FreeBSD.org/mailman/listinfo/svn-src-all[svn-src-all], http://lists.FreeBSD.org/mailman/listinfo/svn-ports-all[svn-ports-all] e http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all[svn-doc-all] são as listas de discussão que o sistema de controle de versão usa para enviar mensagens de commit. _Nunca_ envie e-mail diretamente para essas listas. Apenas envie respostas para esta lista quando elas forem curtas e estiverem diretamente relacionadas a um commit. Lista de discussão dos desenvolvedores do FreeBSD:: Todos os committers estão inscritos na -developers. Esta lista foi criada para ser um fórum para os problemas da "comunidade" dos committers. Exemplos são a eleição do Core Team, anúncios, etc. + A lista de discussão dos desenvolvedores do FreeBSD é para uso exclusivo dos committers do FreeBSD. Para desenvolver o FreeBSD, os committers devem ter a capacidade de discutir abertamente assuntos que serão resolvidos antes de serem anunciados publicamente. As discussões francas sobre o trabalho em andamento não são adequadas para publicação aberta e podem prejudicar o FreeBSD. + Espera-se que todos os committers do FreeBSD não publiquem ou encaminhem mensagens da lista de discussão dos desenvolvedores do FreeBSD fora da lista de membros sem a permissão de todos os autores. Violadores serão removidos da lista de discussão dos desenvolvedores do FreeBSD, resultando em uma suspensão dos privilégios de commit. Violações repetidas ou flagrantes podem resultar na revogação permanente dos privilégios de commit. + _Não_ é a intenção desta lista ser um local para revisões de código ou para realizar qualquer discussão técnica. Na verdade, usá-lo como tal prejudica o Projeto FreeBSD, pois dá uma sensação de uma lista fechada, onde as decisões gerais que afetam toda a comunidade usando o FreeBSD são feitas sem serem "abertas". Por último, mas não menos importante, __nunca, nunca, envie por e-mail a lista de discussão dos desenvolvedores do FreeBSD e faça CC:/BCC: para outra lista do FreeBSD__. Nunca, jamais envie email para outra lista de emails do FreeBSD e faça CC:/BCC: para a lista de discussão dos desenvolvedores do FreeBSD. Fazer isso pode diminuir muito os benefícios dessa lista. [[ssh.guide]] == Guia de início rápido do SSH [.procedure] . Se você não quiser digitar sua senha toda vez que usar o man:ssh[1], e você usa chaves para autenticar, o man:ssh-agent[1] está lá para sua conveniência. Se você quiser usar o man:ssh-agent[1], certifique-se de executá-lo antes de executar os outros aplicativos. Os usuários de X, por exemplo, geralmente fazem isso a partir do [.filename]#.xsession# ou do [.filename]#.xinitrc#. Veja man:ssh-agent[1] para detalhes. . Gere um par de chaves usando man:ssh-keygen[1]. O par de chaves será colocado no diretório [.filename]#$HOME/.ssh/#. + [IMPORTANT] ==== Somente as chaves ECDSA, Ed25519 ou RSA são suportadas. ==== . Envie sua chave pública ([.filename]#$HOME/.ssh/id_ecdsa.pub#, [.filename]#$HOME/.ssh/id_ed25519.pub#, ou [.filename]#$HOME/.ssh/id_rsa.pub#) para a pessoa que está configurando você como um committer para que ela possa ser colocada em [.filename]#yourlogin# in [.filename]#/etc/ssh-keys/# na `freefall`. Agora man:ssh-add[1] pode ser usado para autenticação uma vez por sessão. Ele solicita a frase secreta da chave privada e a armazena no agente de autenticação (man:ssh-agent[1]). Use o `ssh-add -d` para remover as chaves armazenadas no agente. Teste com um simples comando remoto: `ssh freefall.FreeBSD.org ls /usr`. Para obter mais informações, consulte package:security/openssh-portable[], man:ssh[1], man:ssh-add[1], man:ssh-agent[1], man:ssh-keygen[1], e man:scp[1]. Para obter informações sobre como adicionar, alterar ou remover chaves man:ssh[1], consulte https://wiki.freebsd.org/clusteradm/ssh-keys[este artigo]. [[coverity]] == Disponibilidade do Coverity(R) para os Committers do FreeBSD Todos os desenvolvedores do FreeBSD podem obter acesso aos resultados da análise do Coverity de todo o software do Projeto FreeBSD. Todos os interessados em obter acesso aos resultados de análise das execuções automatizadas do Coverity podem se inscrever em http://scan.coverity.com/[Coverity Scan]. O wiki do FreeBSD inclui um mini-guia para desenvolvedores interessados em trabalhar com os relatórios de análise do Coverity(R): https://wiki.freebsd.org/CoverityPrevent[https://wiki.freebsd.org/CoverityPrevent]. Por favor observe que este mini-guia só pode ser lido por desenvolvedores do FreeBSD, então se você não puder acessar esta página, você terá que pedir a alguém para adicioná-lo à lista de acesso apropriada do Wiki. Finalmente, todos os desenvolvedores do FreeBSD que usarão o Coverity(R) são sempre encorajados a pedir mais detalhes e informações sobre o uso, publicando quaisquer perguntas na lista de discussão dos desenvolvedores do FreeBSD. [[rules]] == A Grande Lista de Regras dos Committers do FreeBSD Todos os envolvidos com o projeto FreeBSD devem obedecer ao _Código de Conduta_ disponível em https://www.FreeBSD.org/internal/code-of-conduct/[https://www.FreeBSD.org/internal/code-of-conduct/]. Como committers, vocês formam a face pública do projeto, e como você se comporta tem um impacto vital na percepção pública disso. Este guia expande as partes do _Código de Conduta_ específico para os committers. . Respeite outros committers. . Respeite os outros colaboradores. . Discuta qualquer mudança significativa _antes de_ fazer o commit. . Respeite os mantenedores existentes (se listado no campo `MAINTAINER` no [.filename]#Makefile# ou no [.filename]#MAINTAINER# no diretório de nível superior). . Deve ser feito o rollback de qualquer alteração contestada enquanto estiver pendente a resolução da disputa, se solicitado por um mantenedor. Alterações relacionadas à segurança podem anular os desejos de um mantenedor, a critério do Oficial de Segurança. . As alterações vão para o FreeBSD-CURRENT antes do FreeBSD-STABLE, a menos que especificamente permitido pelo engenheiro de release ou a menos que elas não sejam aplicáveis ao FreeBSD-CURRENT. Qualquer alteração não trivial ou não urgente que seja aplicável também deve ser permitida no FreeBSD-CURRENT por pelo menos 3 dias antes da fusão, para que tenha tempo suficiente de teste. O engenheiro de release tem a mesma autoridade sobre o branch FreeBSD-STABLE, conforme descrito para o mantenedor na regra #5. . Não brigue em público com outros committers; parece ruim. . Respeite todos os congelamentos de código e leia as listas de discussão `committers` e `developers` em tempo hábil para que você saiba quando um congelamento de código está em vigor. . Em caso de dúvida em qualquer procedimento, pergunte primeiro! . Teste suas alterações antes de fazer o commit. . Não commit em software contribuído sem a aprovação _explicita_ dos respectivos mantenedores. Conforme observado, a quebra de algumas dessas regras pode ser motivo para suspensão ou, mediante ofensa repetida, remoção permanente de privilégios de commit. Membros individuais do core têm o poder de suspender temporariamente os privilégios de commit até que o core como um todo tenha a chance de revisar o problema. No caso de uma "emergência" (um committer causando dano ao repositório), uma suspensão temporária também pode ser feita pelos meisters do repositório. Apenas uma maioria de 2/3 do core tem autoridade para suspender os privilégios de confirmação por mais de uma semana ou para removê-los permanentemente. Essa regra não existe para definir o core como um bando de ditadores cruéis que podem se livrar casualmente de committers como se fossem latas de refrigerante vazias, mas para dar ao projeto uma espécie de fusível de segurança. Se alguém está fora de controle, é importante ser capaz de lidar com isso imediatamente, em vez de ficar paralisado pelo debate. Em todos os casos, um committer cujos privilégios foram suspensos ou revogados tem direito a uma "audiência" com o core, sendo a duração total da suspensão determinada naquele momento. Um committer cujos privilégios são suspensos também pode solicitar uma revisão da decisão após 30 dias e a cada 30 dias a partir de então (a menos que o período total de suspensão seja inferior a 30 dias). Um committer cujos privilégios tenham sido revogados completamente pode solicitar uma revisão após um período de 6 meses. Esta política de revisão é _estritamente informal_ e, em todos os casos, o core reserva-se o direito de agir ou desconsiderar os pedidos de revisão se eles sentirem que a decisão original é a correta. Em todos os outros aspectos da operação do projeto, o core é um subconjunto de committers e é limitado pelas __mesmas regras__. Só porque alguém está no core isso não significa que eles têm permissão especial para sair de qualquer uma das linhas pintadas aqui; os "poderes especiais" do core só são aplicados quando ele age como um grupo, não individualmente. Como indivíduos, os membros da equipe principal são todos committers em primeiro lugar e core em segundo. === Detalhes [[respect]] . Respeite outros committers. + Isso significa que você precisa tratar outros committers como os desenvolvedores de grupos pares que eles são. Apesar de nossas tentativas ocasionais de provar o contrário, não se chega a ser um committer por ser estúpido e nada incomoda mais do que ser tratado dessa maneira por um de seus colegas. Se nós sempre sentimos respeito uns pelos outros ou não (e todo mundo tem dias difíceis), nós ainda temos que _tratar_ os outros committers com respeito em todos os momentos, em fóruns públicos e em emails privados. + Ser capaz de trabalhar juntos a longo prazo é o maior patrimônio deste projeto, muito mais importante do que qualquer conjunto de alterações no código, e transformar argumentos sobre código em problemas que afetam nossa capacidade de longo prazo de trabalhar harmoniosamente juntos não vale a pena por qualquer estiramento concebível da imaginação. + Para cumprir esta regra, não envie e-mails quando estiver com raiva ou de alguma forma se comportar de uma maneira que possa causar uma confrontação desnecessária com os outros. Primeiro acalme-se, então pense em como se comunicar da maneira mais eficaz para convencer as outras pessoas de que o seu lado do argumento está correto, não apenas gaste um pouco de vapor para que você possa se sentir melhor a curto prazo às custas de uma guerra de longa duração. Isso não só é uma "economia de energia" muito ruim, mas demonstrações repetidas de agressão pública que prejudicam nossa capacidade de trabalhar bem juntas serão tratadas severamente pela liderança do projeto e podem resultar na suspensão ou término dos seus privilégios de commit. . A liderança do projeto levará em consideração as comunicações públicas e privadas trazidas a ela. Ela não buscará a divulgação de comunicações privadas, mas levará isso em conta se for oferecida de forma voluntária pelos envolvidos na reclamação. + Tudo isso nunca é uma opção que a liderança do projeto goste nem um pouco, mas a união vem em primeiro lugar. Nenhuma quantidade de código ou de bons conselhos vale a pena se trocar desta forma. . Respeite os outros colaboradores. + Você nem sempre foi um committer. Houve uma época em que você era um colaborador. Lembre-se disso em todos os momentos. Lembre-se de como foi tentar obter ajuda e atenção. Não se esqueça de que seu trabalho como colaborador foi muito importante para você. Lembre-se de como foi. Não desencoraje, deprecie ou diminua os colaboradores. Trate-os com respeito. Eles são nossos committers em espera. Eles são tão importantes para o projeto quanto os committers. Suas contribuições são tão válidas e tão importantes quanto as suas. Afinal, você fez muitas contribuições antes de se tornar um committer. Sempre se lembre disso. + Considere os pontos levantados sob <> e aplique-os também aos contribuidores. . Discuta qualquer mudança significativa _antes de_ fazer o commit. + O repositório não é onde as alterações são inicialmente submetidas para correção ou discussão, isso acontece primeiro nas listas de discussão ou pelo uso do serviço do Phabricator. O commit só acontecerá quando algo semelhante a um consenso for alcançado. Isso não significa que a permissão seja necessária antes de corrigir todos os erros óbvios de sintaxe ou erros ortográficos na página manual, significa apenas que é bom desenvolver uma ideia de quando a mudança proposta não é tão óbvia e requer algum feedback primeiro. As pessoas realmente não se importam com mudanças radicais se o resultado for algo claramente melhor do que antes, elas simplesmente não gostam de ser _surpreendidas_ por essas mudanças. A melhor maneira de certificar-se de que as coisas estão no caminho certo é ter o código revisado por um ou mais committers. + Em caso de dúvida, peça por uma revisão! . Respeite os mantenedores existentes, se listados. + Muitas partes do FreeBSD não são "possuídas" no sentido de que qualquer indivíduo específico irá pular e gritar se você enviar uma alteração para a "sua" área, mas ainda vale a pena verificar primeiro. Uma convenção que usamos é colocar uma linha de mantenedor no [.filename]#Makefile# para qualquer pacote ou subárvore que esteja sendo mantido ativamente por uma ou mais pessoas; veja link:{developers-handbook}#policies[Source Tree Guidelines and Policies] para documentação sobre isso. Nas seções de código para quais existirem vários mantenedores, os commits nas áreas afetadas por um mantenedor precisarão ser revisados por pelo menos um outro mantenedor. Nos casos em que o "maintainer-ship" de algo não está claro, consulte os logs do repositório para os arquivos em questão e veja se alguém está trabalhando recentemente ou predominantemente naquela área. . Deve ser feito o rollback de qualquer alteração contestada enquanto estiver pendente a resolução da disputa, se solicitado por um mantenedor. Alterações relacionadas à segurança podem anular os desejos de um mantenedor, a critério do Oficial de Segurança. + Isso pode ser difícil de engolir em momentos de conflito (quando cada lado está convencido de que eles estão certos, é claro), mas um sistema de controle de versão torna desnecessário ter uma disputa em andamento quando é muito mais fácil simplesmente reverter a mudança que gerou a disputa, faça com que todos se acalmem novamente e tente descobrir qual é a melhor maneira de proceder. Se a mudança acaba por ser a melhor coisa depois de tudo, ela pode ser facilmente trazida de volta. Se ela não for, os usuários não terão que viver com a mudança falsa na árvore enquanto todos estavam ocupados debatendo seus méritos. Pessoas _muito_ raramente pedem rollbacks no repositório, uma vez que a discussão geralmente expõe mudanças ruins ou controversas antes que o commit aconteça, mas em raras ocasiões o rollback deve ser feito sem discussão para que possamos entrar imediatamente da discussão do tópico para descobrirmos se ele era adequado ou não. . As alterações vão para o FreeBSD-CURRENT antes do FreeBSD-STABLE, a menos que especificamente permitido pelo engenheiro de release ou a menos que elas não sejam aplicáveis ao FreeBSD-CURRENT. Qualquer alteração não trivial ou não urgente que seja aplicável também deve ser permitida no FreeBSD-CURRENT por pelo menos 3 dias antes da fusão, para que possa ter tempo suficiente de teste. O engenheiro de lançamento tem a mesma autoridade sobre o branch FreeBSD-STABLE, conforme descrito na regra #5. + Este é outro problema do tipo "não discuta sobre isso", já que é o engenheiro de release quem é o responsável final (e é espancado) se uma mudança for ruim. Por favor, respeite isso e dê ao engenheiro de release a sua total cooperação quando se trata do branch FreeBSD-STABLE. O gerenciamento do FreeBSD-STABLE pode frequentemente parecer excessivamente conservador para o observador casual, mas também deve ter em mente o fato de que o conservadorismo deve ser a marca do FreeBSD-STABLE e regras diferentes aplicam-se lá do que no FreeBSD-CURRENT. Também não há sentido em fazer com que o FreeBSD-CURRENT seja um campo de testes se as alterações forem mescladas no FreeBSD-STABLE imediatamente. Mudanças precisam de uma chance de serem testadas pelos desenvolvedores do FreeBSD-CURRENT, então espere algum tempo antes da fusão, a menos que a correção do FreeBSD-STABLE seja crítica, sensível ao tempo ou óbvia a ponto de tornar desnecessário testes adicionais (correções ortográficas nas páginas de manual) correções de erros / erros de digitação, etc.) Em outras palavras, aplique o bom senso. + Mudanças nas branches de segurança (por exemplo, `releng/9.3`) devem ser aprovadas por um membro da Equipe de Segurança mailto:security-officer@FreeBSD.org[security-officer@FreeBSD.org], ou em alguns casos , por um membro da Equipe de Engenharia de Release mailto:re@FreeBSD.org[re@FreeBSD.org]. . Não brigue em público com outros committers; parece ruim. + Este projeto tem uma imagem pública a defender e essa imagem é muito importante para todos nós, especialmente se quisermos continuar a atrair novos membros. Haverá ocasiões em que, apesar das melhores tentativas de autocontrole de todos, os ânimos se perdem e palavras de raiva são trocadas. A melhor coisa que pode ser feita nesses casos é minimizar os efeitos disso até que todos tenham esfriado. Não divulgue palavras iradas em público e não encaminhe correspondências privadas ou outras comunicações privadas para listas publicas de discussão, aliases de mensagens, canais de mensagens instantâneas ou sites de mídia social. O que as pessoas dizem um-para-um é frequentemente muito menos revestido de açúcar do que o que eles diriam em público, e tais comunicações, portanto, não têm lugar lá - elas servem apenas para inflamar uma situação já ruim. Se a pessoa que enviou um flame-o-grama tiver pelo menos a elegância de enviá-lo em particular, então tenha a elegância de mantê-lo em sigilo. Se você acha que está sendo tratado injustamente por outro desenvolvedor e está lhe causando angústia, traga o assunto para o core em vez de torná-lo público. O Core fará o seu melhor para atuar como pacificadores e trazer as coisas de volta para a sanidade. Nos casos em que a disputa envolve uma alteração na base de código e os participantes não parecem estar chegando a um acordo amigável, o core pode nomear um terceiro mutuamente aceitável para resolver a disputa. Todas as partes envolvidas devem então concordar em se comprometer com a decisão tomada por este terceiro. . Respeite todos os congelamentos de código e leia atempadamente a lista de discussão `committers` e `developers` para saber quando um congelamento de código está em vigor. + Efetuar o commit de alterações não aprovadas durante um congelamento de código é um erro realmente grande e espera-se que os committers se mantenham atualizados sobre o que está acontecendo antes de entrar depois de uma longa ausência e fazer o commit de 10 megabytes de material acumulado. As pessoas que abusarem disso regularmente terão seus privilégios de commit suspensos até que eles voltem do FreeBSD Happy Reeducation Camp que mantemos na Groenlândia. . Em caso de dúvida em qualquer procedimento, pergunte primeiro! + Muitos erros são cometidos porque alguém está com pressa e apenas assume que sabe a forma certa para fazer alguma coisa. Se você não fez isso antes, é bem provável que você não conheça realmente a maneira como fazemos as coisas e realmente precise perguntar primeiro ou você vai se envergonhar completamente em público. Não há vergonha em perguntar "como diabos eu faço isso?" Já sabemos que você é uma pessoa inteligente; caso contrário, você não seria um committer. . Teste suas alterações antes de fazer o commit. + Isso pode parecer óbvio, mas se realmente fosse tão óbvio, provavelmente não veríamos tantos casos de pessoas claramente não fazendo isso. Se suas mudanças são para o kernel, certifique-se de que você ainda pode compilar o GENERIC e o LINT. Se as suas alterações estiverem em outro lugar, certifique-se de que você ainda pode fazer um "make world". Se as alterações forem feitas em uma branch, certifique-se de que seu teste ocorra com uma máquina que esteja executando esse código. Se você tiver uma alteração que também possa quebrar outra arquitetura, verifique e teste em todas as arquiteturas suportadas. Por favor, consulte a https://www.FreeBSD.org/internal/[Página Interna do FreeBSD] para obter uma lista dos recursos disponíveis. À medida que outras arquiteturas são adicionadas à lista de plataformas suportadas do FreeBSD, os recursos de teste compartilhados apropriados serão disponibilizados. . Não commit em software contribuído sem a aprovação _explicita_ dos respectivos mantenedores. + Software contribuído é qualquer código que esteja sob as árvores [.filename]#src/contrib#, [.filename]#src/crypto#, ou [.filename]#src/sys/contrib#. + As árvores mencionadas acima são para software contribuído geralmente importado para um branch de fornecedor. Fazer o commit de algo lá pode causar dores de cabeça desnecessárias quando for importado novas versões do software. Uma regra geral é considerar enviar os patches upstream diretamente para o fornecedor. Patches podem ser committados primeiramente no FreeBSD, desde que tenha a permissão do mantenedor. + As razões para modificar o software upstream variam entre querer controle estrito sobre uma dependência fortemente acoplada à falta de portabilidade na distribuição do repositório canônico do seu código. Independentemente do motivo, o esforço para minimizar a carga de manutenção do fork é útil para outros mantenedores. Evite realizar commits de alterações triviais ou cosméticas nos arquivos, pois isso dificulta cada merge: esses patches precisam ser verificados manualmente a cada importação. + Se uma parte específica do software não tiver um mantenedor, você é incentivado a assumir a propriedade. Se você não tiver certeza sobre o mantenedor atual, envie um email para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-arch[lista de email de arquitetura e design do FreeBSD] e pergunte. === Política sobre Várias Arquiteturas O FreeBSD adicionou ports para várias novas arquiteturas durante os ciclos de release recentes e realmente não é mais um sistema operacional centrado em i386(TM). Em um esforço para tornar mais fácil manter o FreeBSD portátil entre as plataformas que suportamos, o core desenvolveu este mandato: [.blockquote] Nossa plataforma de referência de 32 bits é a i386 e a nossa plataforma de referência de 64 bits é amd64. O principal trabalho de design (incluindo as principais alterações da API e da ABI) deve ser comprovado em pelo menos uma plataforma de 32 bits e pelo menos uma de 64 bits, preferencialmente nas plataformas de referência primária, antes que o seu commit possa ser feito na árvore de fontes. As plataformas i386 e amd64 foram escolhidas por estarem mais prontamente disponíveis para os desenvolvedores e como representantes dos mais diversos designs de processador e de sistema - "big versus little endian", registrador de arquivos versus pilha de registro, diferentes implementações de DMA e cache, tabelas de página de hardware versus gerenciamento de TLB de software, etc. Continuaremos a reavaliar essa política, já que o custo e a disponibilidade das plataformas de 64 bits mudam. Os desenvolvedores também devem estar cientes da nossa Política de Tier para o suporte de longo prazo das arquiteturas de hardware. As regras aqui pretendem fornecer orientação durante o processo de desenvolvimento e são diferentes dos requisitos de recursos e arquiteturas listados nessa seção. As regras de Tier para suporte de recursos em arquiteturas no momento da release são mais rigorosas do que as regras para alterações durante o processo de desenvolvimento. === Outras Sugestões Ao enviar alterações na documentação, use um verificador ortográfico antes de efetuar o commit. Para todos os documentos XML, verifique se as diretivas de formatação estão corretas executando o `make lint` e o package:textproc/igor[]. Para as páginas de manual, execute o package:sysutils/manck[] e o package:textproc/igor[] na página de manual para verificar se todas as referências cruzadas e referências de arquivo estão corretas e se a página man possui todos os `MLINKS` apropriados instalados. Não misture correções de estilo com novas funcionalidades. Uma correção de estilo é qualquer alteração que não modifique a funcionalidade do código. Misturar as alterações ofusca a mudança de funcionalidade ao solicitar a comparação das diferenças entre as revisões, o que pode ocultar quaisquer novos bugs. Não inclua alterações de espaço em branco com alterações de conteúdo nos commits para [.filename]#doc/#. A desordem extra nos diffs torna o trabalho dos tradutores muito mais difícil. Em vez disso, faça qualquer alteração de estilo ou espaço em branco em commits separados e que sejam claramente rotuladas como tal na mensagem de commit. === Recursos Obsoletos (Deprecated) Quando for necessário remover uma funcionalidade de software do sistema básico, siga estas diretrizes sempre que possível: . Uma menção é feita na página de manual e, possivelmente, nas notas de versão que a opção, o utilitário ou a interface estão obsoletos. O uso do recurso obsoleto gera um aviso. . A opção, utilitário ou interface é preservada até a próxima release principal (ponto zero). . A opção, o utilitário ou a interface são removidos e não são mais documentados. Agora está obsoleto. Também é geralmente uma boa ideia anotar sua remoção nas notas de release. === Privacidade e Confidencialidade . A maioria dos negócios do FreeBSD é feita em público. + O FreeBSD é um projeto __aberto__. O que significa que não só alguém pode usar o código-fonte, mas que a maior parte do processo de desenvolvimento está aberto ao escrutínio público. . Certos assuntos delicados devem permanecer privados ou mantidos sob embargo. + Infelizmente, não pode haver transparência completa. Como desenvolvedor do FreeBSD, você terá um certo grau de acesso privilegiado à informação. Consequentemente, espera-se que você respeite certos requisitos de confidencialidade. Às vezes, a necessidade de confidencialidade vem de colaboradores externos ou tem um limite de tempo específico. Principalmente, porém, é uma questão de não liberar comunicações privadas. . O oficial de segurança tem controle exclusivo sobre a liberação de alertas de segurança. + Onde existem problemas de segurança que afetam muitos sistemas operacionais diferentes, o FreeBSD frequentemente depende do acesso antecipado para poder preparar alertas para liberação coordenada. A menos que se possa confiar nos desenvolvedores do FreeBSD para manter a segurança, esse acesso antecipado não será disponibilizado. O Oficial de Segurança é responsável por controlar o acesso pré-lançamento às informações sobre vulnerabilidades, e por definir o momento de liberação de todos os alertas. Ele pode solicitar ajuda sob condição de confidencialidade de qualquer desenvolvedor com conhecimento relevante para preparar as correções de segurança. . As comunicações com o Core são mantidas confidenciais pelo tempo que for necessário. + As comunicações para o core serão inicialmente tratadas como confidenciais. Eventualmente, no entanto, a maioria dos negócios do Core serão resumidos nos relatórios mensais ou trimestrais do core. Cuidado será tomado para evitar a divulgação de detalhes sensíveis. Os registros de alguns assuntos particularmente sensíveis podem não ser relatados e serão mantidos apenas nos arquivos privados do Core. . Acordos de não divulgação (NDA) podem ser necessários para o acesso a determinados dados comercialmente sensíveis. + O acesso a determinados dados comercialmente sensíveis só pode estar disponível sob um Contrato de Não Divulgação. A equipe jurídica da Fundação FreeBSD deve ser consultado antes de qualquer acordo vinculativo ser firmado. . Comunicações privadas não devem ser tornadas públicas sem permissão. + Além dos requisitos específicos acima, há uma expectativa geral de não publicar comunicações privadas entre desenvolvedores sem o consentimento de todas as partes envolvidas. Peça permissão antes de encaminhar uma mensagem para uma lista de discussão pública, ou publicá-la em um fórum ou site que possa ser acessado por outros que não os correspondentes originais. . As comunicações em canais de acesso restrito ou somente do projeto devem ser mantidas em sigilo. + Semelhantemente às comunicações pessoais, certos canais de comunicação interna, incluindo as listas de discussão dos Committers do FreeBSD e os canais de IRC de acesso restrito, são considerados comunicações privadas. A permissão é necessária para publicar material dessas fontes. . O Core pode aprovar a publicação. + Quando for impraticável obter permissão devido ao número de correspondentes ou quando a permissão para publicar for injustificadamente retida, a Core poderá aprovar a liberação de tais assuntos privados que mereçam uma publicação mais geral. [[archs]] == Suporte para Várias Arquiteturas O FreeBSD é um sistema operacional altamente portátil destinado a funcionar em muitos tipos diferentes de arquiteturas de hardware. Manter uma separação clara entre o código dependente de máquina (MD) e independente de máquina (MI), além de minimizar o código MD, é uma parte importante da nossa estratégia de permanecer ágil em relação às tendências atuais de hardware. Cada nova arquitetura de hardware suportada pelo FreeBSD aumenta substancialmente o custo de manutenção de código, de suporte do toolchain e de engenharia de release. Também aumenta drasticamente o custo do teste efetivo das alterações no kernel. Como tal, há uma forte motivação para diferenciar as classes de suporte para as várias arquiteturas, permanecendo forte em algumas arquiteturas chaves que são vistas como o "público-alvo" do FreeBSD. === Declaração de Intenção Geral O projeto FreeBSD tem como objetivo a "qualidade comercial de produção off-the-shelf (COTS) para workstations, servidores e sistemas embarcados de ponta". Mantendo o foco em um conjunto restrito de arquiteturas de interesse nesses ambientes, o Projeto FreeBSD é capaz de manter altos níveis de qualidade, estabilidade e desempenho, bem como de minimizar a carga de várias equipes de suporte no projeto, como a equipe de ports, a equipe de documentação, o oficial de segurança e as equipes de engenharia de release. A diversidade no suporte de hardware amplia as opções para os consumidores do FreeBSD oferecendo novos recursos e oportunidades de uso, mas esses benefícios devem sempre ser cuidadosamente considerados em termos do custo de manutenção no mundo real associado ao suporte adicional à plataforma. O projeto FreeBSD diferencia plataforma alvos em quatro camadas. Cada camada inclui uma lista de garantias que os consumidores podem confiar , bem como as obrigações por Projeto e desenvolvedores para cumprir essas garantias. Esta lista define o mínimo de garantia por cada camada. O Projeto e desenvolvedores podem prover leveis de suporte adicionais além da garantia mínima dada a uma camada, mas tais suportes adicionais não tem garantias. Cada plataforma alvo é designada para uma camada especifica para cada ramificação stable. Como resultado, a plataforma alvo poderia ser designada para diferentes camadas em ramificações stable concorrentes. === Plataformas Alvo O suporte para uma plataforma de hardware consiste em dois componentes: suporte ao kernel e interfaces binárias de aplicativos (ABIs) do usuário. O suporte do kernel à plataforma inclui os itens necessários para executar um kernel do FreeBSD em uma plataforma de hardware, como gerenciamento de memória virtual dependente de máquina e drivers de dispositivo. Uma ABI especifica uma interface para os processos do usuário interagirem com o kernel do FreeBSD e as bibliotecas do sistema base. Uma ABI inclui interfaces de chamada do sistema, o layout e a semântica de estruturas de dados públicos e o layout e a semântica de argumentos transmitidos às sub-rotinas. Alguns componentes de uma ABI podem ser definidos por especificações tais como o layout dos objetos de exceção C ++ ou as convenções de chamada para funções C. Um kernel do FreeBSD também usa uma ABI (às vezes chamada de Interface Binária do Kernel (KBI)) que inclui a semântica e layouts de estruturas de dados públicos e o layout e semântica de argumentos para funções públicas dentro do próprio kernel. Um kernel do FreeBSD pode suportar múltiplas ABIs de usuário. Por exemplo, o kernel amd64 do FreeBSD suporta as ABIs de usuário do FreeBSD amd64 e i386, bem como as ABIs de usuário do Linux x86_64 e i386. Um kernel do FreeBSD deve suportar uma ABI "nativa" como a ABI padrão. A "ABI" nativa geralmente compartilha certas propriedades com a ABI do kernel, como a convenção de chamada C, tamanhos dos tipos básicos, etc. Os Tiers são definidos tanto para os kernels quanto para as ABIs do usuário. Normalmente, o kernel de uma plataforma e as ABIs do FreeBSD são atribuídas à mesma Tier. === Tier 1: Arquiteturas Completamente Suportadas As plataformas Tier 1 são as plataformas mais maduras do FreeBSD. Elas são suportadas pelas equipes de segurança, engenharia de release e gerenciamento de ports. Espera-se que as arquiteturas Tier 1 estejam com Qualidade de Produção em relação a todos os aspectos do sistema operacional FreeBSD, incluindo ambientes de instalação e desenvolvimento. O Projeto FreeBSD fornece as seguintes garantias aos consumidores das plataformas de Tier 1: * Imagens oficiais de Release do FreeBSD serão fornecidas pela equipe de engenharia de release. * Serão fornecidas atualizações binárias e patches no formato de código fonte para os Avisos de Segurança e Avisos de Erro das versões suportadas. * Serão fornecidos patches de código fonte para os avisos de segurança das branches suportadas. * Atualizações binárias e patches de código fonte geralmente são fornecidos para os avisos de segurança multiplataforma no momento do anúncio. * As alterações nas ABIs do usuário geralmente incluirão bibliotecas de compatibilidade para garantir a operação correta dos binários compilados a partir de qualquer branch estável de uma plataforma Tier 1. Estas bibliotecas podem não ser ativadas na instalação padrão. Se as bibliotecas de compatibilidade não forem fornecidas para uma alteração de ABI, a falta da mesma estará claramente documentada nas notas de versão. * Alterações em certas partes da ABI do kernel incluirão bibliotecas de compatibilidade para garantir a operação correta dos módulos do kernel compilados contra a versão suportada mais antiga da branch. Observe que nem todas as partes da ABI do kernel estão protegidas. * Pacotes binários oficiais para softwares de terceiros serão fornecidos pela equipe de ports. Para arquiteturas embarcadas, esses pacotes podem ser compilados de forma cruzada a partir de uma arquitetura diferente. * Os ports mais relevantes devem ou compilar ou ter filtros apropriados para prevenir a compilação dos inadequados. * Novos recursos que não são inerentemente específicos da plataforma serão totalmente funcionais em todas as arquiteturas de Tier 1. * Os recursos e bibliotecas de compatibilidade usados pelos binários compilados a partir das branchs estáveis mais antigas podem ser removidos nas versões principais mais recentes. Essas remoções serão claramente documentadas nas notas de versão. * As plataformas Tier 1 devem ser totalmente documentadas. As operações básicas serão documentadas no Handbook do FreeBSD. * As plataformas de Tier 1 serão incluídas na árvore de código fonte. * As plataformas de Tier 1 devem ser auto-hospedadas ou por meio de um toolchain disponível na árvore de código fonte ou por meio de um toolchain externo. Se um toolchain externo for necessário, serão fornecidos pacotes binários oficiais para o toolchain externo. Para manter a maturidade das plataformas de Tier 1, o Projeto FreeBSD manterá os seguintes recursos para apoiar o desenvolvimento: * Suporte à automação do processo de compilação e de testes no cluster FreeBSD.org ou em algum outro local facilmente disponível para todos os desenvolvedores. Plataformas embarcadas podem substituir um emulador disponível no cluster FreeBSD.org por hardware real. * A inclusão nos targets do `make universe` e `make tinderbox`. * Hardware dedicado em um dos clusters do FreeBSD para compilação de pacotes (nativamente ou via qemu-user). Coletivamente, os desenvolvedores devem fornecer o seguinte para manter o status de Tier 1 de uma plataforma: * Alterações na árvore de código fonte não devem quebrar conscientemente a compilação de uma plataforma de Tier 1. * As arquiteturas de Tier 1 devem ter um ecossistema maduro e saudável de usuários e desenvolvedores ativos. * Os desenvolvedores devem ser capazes de compilar pacotes em sistemas Tier 1 não-embarcados comumente disponíveis. Isso pode significar compilações nativas se sistemas não-embarcados estiverem normalmente disponíveis para a plataforma em questão, ou significar compilações cruzadas hospedadas em alguma outra arquitetura de Tier 1. * As alterações não podem quebrar a ABI do usuário. Se for necessária uma alteração da ABI, a compatibilidade da ABI com os binários existentes deve ser provida através do versionamento de símbolos ou do versionamento de bibliotecas compartilhadas. * Alterações mescladas em branchs estáveis não podem quebrar as partes protegidas da ABI do kernel. Se for necessária uma alteração da ABI do kernel, ela deverá ser modificada para preservar a funcionalidade dos módulos existentes do kernel. === Tier 2: Arquiteturas de Desenvolvimento e Nicho As plataformas de Tier 2 são funcionais, mas são plataformas FreeBSD menos maduras. Elas não são suportadas pelas equipes de segurança, engenharia de release e gerenciamento de ports. As plataformas Tier 2 podem ser candidatas à plataforma Tier 1 que ainda estão em desenvolvimento ativo. As arquiteturas que atingem o fim da vida útil também podem ser movidas do status de Tier 1 para o status de Tier 2 à medida que a disponibilidade de recursos para continuar a manter o sistema em um estado de Qualidade de Produção diminui. Arquiteturas de nicho bem suportadas também podem ser de Tier 2. O Projeto FreeBSD fornece as seguintes garantias aos consumidores das plataformas de Tier 2: * A infraestrutura de ports deve incluir suporte básico para as arquiteturas de Tier 2 suficiente para suportar a compilação de ports e pacotes. Isso inclui suporte para pacotes básicos, tais como o ports-mgmt/pkg, mas não há garantia de que ports arbitrários serão compiláveis ou funcionais. * Novos recursos que não são inerentemente específicos da plataforma devem ser viáveis em todas as arquiteturas de Tier 2 se não implementados. * As plataformas de Tier 2 serão incluídas na árvore de código fonte. * As plataformas de Tier 2 devem ser auto-hospedadas ou por meio de um toolchain disponível na árvore de código fonte ou por meio de um toolchain externo. Se um toolchain externo for necessário, serão fornecidos pacotes binários oficiais para o toolchain externo. * As plataformas de Tier 2 devem fornecer kernels e espaço de usuário funcionais, mesmo que uma release oficial não seja provida. Para manter a maturidade das plataformas de Tier 2, o Projeto FreeBSD manterá os seguintes recursos para apoiar o desenvolvimento: * A inclusão nos targets do `make universe` e `make tinderbox`. Coletivamente, os desenvolvedores devem fornecer o seguinte para manter o status de Tier 2 de uma plataforma: * Alterações na árvore de código fonte não devem quebrar conscientemente a compilação de uma plataforma de Tier 2. * As arquiteturas de Tier 2 devem ter um ecossistema ativo de usuários e desenvolvedores. * Embora sejam permitidas alterações que quebrem a ABI do usuário, a ABI não deve ser quebrada gratuitamente. Alterações significativas da ABI do usuário devem ser restritas às versões principais. * Novos recursos que ainda não foram implementados nas arquiteturas de Tier 2 devem fornecer um meio de desativá-los nessas arquiteturas. === Tier 3: Arquiteturas Experimentais As plataformas de Tier 3 têm pelo menos suporte parcial ao FreeBSD. Elas _não_ são suportadas pelas equipes de segurança, engenharia de release e de gerenciamento de ports. As plataformas de Tier 3 são arquiteturas nos estágios iniciais de desenvolvimento, para plataformas de hardware não convencionais, ou que são considerados sistemas legados improváveis de serem amplamente utilizados no futuro. O suporte inicial para plataformas de Tier 3 pode existir em um repositório separado em vez do repositório de código fonte principal. O Projeto FreeBSD não oferece garantias aos consumidores das plataformas de Tier 3 e não está comprometido em manter recursos para apoiar o seu desenvolvimento. As plataformas de Tier 3 nem sempre podem ser compiláveis, nem quaisquer ABIs do kernel ou de usuário são consideradas estáveis. === Tier 4: Arquiteturas Não Suportadas As plataformas Tier 4 não são suportadas de nenhuma forma pelo projeto. Todos os sistemas não classificados de outra forma são sistemas de Tier 4. Quando uma plataforma faz a transição para o Tier 4, todo o suporte para a plataforma é removido das árvores de código fonte e de ports. Observe que o suporte aos ports deve ser mantido enquanto a plataforma for suportada em uma branch suportada pelo ports. === Política para Alteração do Tier de uma Arquitetura Os sistemas só podem ser movidos de um Tier para outro por meio da aprovação do Core Team do FreeBSD, que deve tomar essa decisão em colaboração com as equipes de segurança, engenharia de release e gerenciamento dos ports. Para que uma plataforma seja promovida para um Tier superior, todas as garantias de suporte ausentes devem ser atendidas antes que a promoção seja concluída. [[ports]] == FAQ específico dos Ports .Adicionando um Novo Port [[ports-qa-add-new]] === Como eu adiciono um novo port? Primeiro, por favor leia a seção sobre cópias do repositório. A maneira mais fácil de adicionar um novo port é o script `addport` localizado no diretório [.filename]#ports/Tools/scripts#. Ele adiciona um port do diretório especificado, determinando a categoria automaticamente a partir do [.filename]#Makefile# do port. Também adiciona uma entrada à categoria do [.filename]#Makefile# do port. Foi escrito por Michael Haro mailto:mharo@FreeBSD.org[mharo@FreeBSD.org], Will Andrews mailto:will@FreeBSD.org[will@FreeBSD.org] e Renato Botelho mailto:garga@FreeBSD.org[garga@FreeBSD.org]. Ao enviar perguntas sobre este script para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[lista de discussão dos ports do FreeBSD], por favor também copie Chris Rees mailto:crees@FreeBSD.org[crees@FreeBSD.org], o mantenedor atual. [[ports-qa-add-new-extra]] === Existe qualquer outra coisa que preciso saber quando adiciono um novo port? Verifique o port, de preferência para garantir que ele seja compilado e empacotado corretamente. Essa é a seqüência recomendada: [source,shell] .... # make install # make package # make deinstall # pkg add package you built above # make deinstall # make reinstall # make package .... O link:{porters-handbook}[Manual de Porters] contém instruções mais detalhadas. Use o man:portlint[1] para verificar a sintaxe do port. Você não precisa necessariamente eliminar todos os avisos, mas certifique-se de ter corrigido os mais simples. Se o port veio de um remetente que não contribuiu para o projeto antes, adicione o nome dessa pessoa a seção link:{contributors}#contrib-additional[Colaboradores Adicionais] da Lista de Colaboradores do FreeBSD. Feche o PR se o port entrou como um PR. Para fechar um PR, mude o estado para `Issue Resolved` e a resolução como `Fixed`. [[non-committers]] == Problemas Específicos para Desenvolvedores Que Não São Committers Algumas pessoas que têm acesso às máquinas do FreeBSD não possuem commit bits. Quase todo este documento também será aplicado a esses desenvolvedores (exceto itens específicos de commits e associações de listas de discussão que os acompanham). Em particular, recomendamos que você leia: * <> * <> + [NOTE] ==== Peça ao seu mentor para adicioná-lo em "Colaboradores Adicionais" ([.filename]#doc/en_US.ISO8859-1/articles/contributors/contrib.additional.xml#), se você ainda não estiver listado há. ==== * <> * <> * <> [[google-analytics]] == Informações sobre o Google Analytics A partir de 12 de dezembro de 2012, o Google Analytics foi habilitado no site do Projeto FreeBSD para coletar estatísticas anônimas sobre o uso do site. As informações coletadas são valiosas para o Projeto de Documentação do FreeBSD, para identificar vários problemas no site do FreeBSD. [[google-analytics-policy]] === Política Geral do Google Analytics O projeto FreeBSD leva a privacidade do visitante muito a sério. Como tal, o site do Projeto FreeBSD honra o cabeçalho "Do Not Track"__antes__ de buscar o código de monitoramento do Google. Para mais informações, consulte a https://www.FreeBSD.org/privacy/[Política de Privacidade do FreeBSD]. O acesso do Google Analytics _não_ é arbitrariamente permitido - o acesso deve ser solicitado, votado pela Equipe de Engenharia de Documentação mailto:doceng@FreeBSD.org[doceng@FreeBSD.org] e explicitamente concedido. Solicitações de acesso aos dados do Google Analytics devem incluir uma finalidade específica. Por exemplo, uma razão válida para solicitar acesso seria "para ver os navegadores web usados com mais freqüência pelos visitantes do website do FreeBSD para garantir que as velocidades de renderização da página sejam aceitáveis." Por outro lado, "ver quais navegadores são usados com mais freqüência" (sem declarar __por que__) seria rejeitado. Todas as solicitações devem incluir o período de tempo para o qual os dados seriam requisitados. Por exemplo, deve ser explicitamente declarado se os dados solicitados seriam requisitados em um período de tempo que abranja um período de 3 semanas, ou se o pedido seria para acessar apenas uma vez. Qualquer pedido de dados do Google Analytics sem uma razão clara e razoável que beneficie o Projeto FreeBSD será rejeitado. [[google-analytics-data]] === Dados disponíveis por meio do Google Analytics Alguns exemplos dos tipos de dados do Google Analytics disponíveis incluem: * Navegadores Web comumente usados * Tempos de carregamento de páginas * Acesso ao site por idioma [[misc]] == Perguntas Diversas === Como adiciono um novo arquivo a uma branch? Para adicionar um arquivo a uma branch, simplesmente faça o check-out ou atualize-o na branch que você deseja adicionar e, em seguida, adicione o arquivo usando a operação add como faria normalmente. Isso funciona bem para as árvores `doc` e `ports`. A árvore `src` usa o SVN e requer mais cuidado por causa das propriedades `mergeinfo`. Veja o <> para detalhes sobre como executar um MFC. === Como eu acesso people.FreeBSD.org para colocar informações pessoais ou de projeto? O servidor `people.FreeBSD.org` é o mesmo que `freefall.FreeBSD.org`. Basta criar um diretório [.filename]#public_html#. Qualquer coisa que você colocar nesse diretório será automaticamente visível em https://people.FreeBSD.org/[https://people.FreeBSD.org/]. === Onde estão armazenados os arquivos da lista de discussão? As listas de discussão são arquivadas em [.filename]#/local/mail# na `freefall.FreeBSD.org`. === Eu gostaria de ser mentor de um novo committer. Qual processo eu preciso seguir? Consulte o documento https://www.freebsd.org/internal/new-account/[Novo Procedimento para Criação de Conta] nas páginas internas. [[benefits]] == Benefícios e vantagens para os Commiters do FreeBSD [[benefits-recognition]] === Reconhecimento O reconhecimento como engenheiro de software competente é o valor mais duradouro. Além disso, ter a chance de trabalhar com algumas das melhores pessoas que todos os engenheiros sonham em conhecer é um grande privilégio! [[benefits-freebsdmall]] === FreeBSD Mall Os committers do FreeBSD podem obter um conjunto gratuito de 4-CDs ou DVDs da http://www.freebsdmall.com[FreeBSD Mall, Inc.] em conferências. [[benefits-irc]] === IRC Além disso, os desenvolvedores podem solicitar um "cloaked hostmask" para sua conta na rede Freenode de IRC na forma de `freebsd/developer/_nome_na_freefall_` ou `freebsd/developer/_nome_no_NickServ_`. Para solicitar uma máscara, envie um e-mail para mailto:irc@FreeBSD.org[irc@FreeBSD.org] com o nome da sua hostmask solicitada e nome da conta no NickServ. [[benefits-gandi]] === `Gandi.net` A Gandi fornece hospedagem de sites, computação em nuvem, registro de domínio e serviços de certificados X.509. A Gandi oferece um desconto E-rate para todos os desenvolvedores do FreeBSD. Envie e-mail para mailto:non-profit@gandi.net[non-profit@gandi.net] usando o seu endereço de e-mail `@freebsd.org` e indique o seu identificador no Gandi. diff --git a/documentation/content/pt-br/articles/contributing/_index.adoc b/documentation/content/pt-br/articles/contributing/_index.adoc index d4650dd374..17e116a34d 100644 --- a/documentation/content/pt-br/articles/contributing/_index.adoc +++ b/documentation/content/pt-br/articles/contributing/_index.adoc @@ -1,425 +1,435 @@ --- title: Contribuindo com o FreeBSD authors: - author: Jordan Hubbard - author: Sam Lawrance - author: Mark Linimon releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "ieee", "general"] --- = Contribuindo com o FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este artigo descreve maneiras diferentes sobre como um indivíduo ou organização pode contribuir com o Projeto FreeBSD. ''' toc::[] Então você quer contribuir com o FreeBSD? Isso é ótimo! O FreeBSD _depende_ das contribuições da sua base de usuários para sobreviver. Suas contribuições não são apenas apreciadas, elas são vitais para que o FreeBSD continue crescendo. Um grande e crescente número de contribuidores internacionais, de uma grande variedade de idade e áreas de conhecimento técnico, desenvolvem o FreeBSD. Sempre existe mais trabalho a ser feito do que pessoas disponíveis para realizá-lo, e mais ajuda é sempre bem vinda. Como um voluntário, o que você pode fazer só é limitado pelo que você quer fazer. Entretanto, o que lhe pedimos é que esteja ciente a respeito do que outros membros da comunidade FreeBSD esperará de você. Você pode querer levar isso em consideração antes de decidir se voluntariar. O Projeto FreeBSD é responsável por um ambiente completo de sistema operacional, em vez de apenas um kernel ou alguns utilitários dispersos. Assim sendo, nossa lista [.filename]#TODO# passa por uma grande variedade de tarefas: da documentação do sistema, testes de versão beta e apresentação, ao instalador do sistema e outros tipos altamente especializados de desenvolvimento do kernel. Pessoas de qualquer nível de conhecimento, em quase qualquer área, quase que certamente poderá ajudar no projeto. Entidades comerciais engajadas em iniciativas relacionadas ao FreeBSD também são encorajadas a entrar em contato conosco. Você precisa de uma extensão especial para fazer seu produto funcionar? Você vai nos encontrar receptivos às suas solicitações, considerando que não sejam muito estranhas. Está trabalhando em um produto de valor adicionado? Por favor nos informe! Podemos ser capazes de trabalhar cooperativamente em algum aspecto dele. O mundo do software livre está desafiando muitas premissas sobre como um software é desenvolvido, vendido e mantido, e nós pedimos que você pelo de uma segunda olhada. [[contrib-what]] == O que é necessário A lista de tarefas e sub-projetos a seguir representa algo como uma amálgama de várias listas de [.filename]#TODO# e outras solicitações. [[non-programmer-tasks]] === Tarefas em execução por não-programadores. Muitas pessoas que estão envolvidas com o FreeBSD não são programadores. O Projeto inclui escritores de documentação, Web designers, e pessoas de suporte. Todas estas pessoas contribuem investindo tempo e sua vontade de aprender. . Leia o FAQ e Handbook periodicamente. Se algo estiver explicado de forma pobre, ambígua, desatualizada ou incorreta, nos comunique. Melhor ainda, envie-nos uma versão ajustada (O formato Docbook não é difícil de aprender, mas não existem objeções em relação ao envio de material no formato ASCII). . Ajude a traduzir a documentação do FreeBSD para a sua linguagem nativa. Se a documentação já existe na sua língua, você pode ajudar a traduzir documentos adicionais ou verificar se as traduções estão atualizadas e corretas. Primeiro dê uma olhada no link:{fdp-primer}#translations/[FAQ de Traduções] contido no Manual de Documentação do Projeto FreeBSD. Você não estará se comprometendo a traduzir toda a documentação do FreeBSD fazendo isto - como um voluntário, você pode fazer tantas quantas traduções desejar. Uma vez que alguém começa a traduzir, outros se unem ao esforço. Se você tem tempo ou energia para traduzir apenas uma parte da documentação, por favor traduza as instruções de instalação. . Leia a http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions[lista de discussão para perguntas gerais sobre o FreeBSD] ocasionalmente (ou regularmente se possível). Pode ser muito recompensador compartilhar a sua experiência e ajudar outras pessoas a resolverem seus problemas; Às vezes você poderá até aprender algo novo! Estes fóruns também podem ser uma fonte de ideias de coisas a serem melhoradas. [[ongoing-programmer-tasks]] === Tarefas em execução por programadores A maioria das tarefas listadas aqui requerem um investimento considerável de tempo ou conhecimento profundo do kernel do FreeBSD; ou, ambos. Entretanto, também existem muitas tarefas úteis que são apropriadas para os "hackers de final de semana". . Se você executa o FreeBSD-CURRENT e possui uma boa conexão com a Internet, existe uma máquina `current.FreeBSD.org` a qual compila uma release completa uma vez por dia - de vez em quando, tente instalar uma destas versões e informe quaisquer problemas no processo. . Leia a http://lists.FreeBSD.org/mailman/listinfo/freebsd-bugs[Lista de discussão de relatórios de problemas do FreeBSD]. Talvez exista um problema que você possa comentar construtivamente ou existam correções que você possa testar. Ou você pode até consertar um dos problemas por conta própria. . Se você souber de qualquer problema que tenha sido corrigido com sucesso no -CURRENT e cuja correção não tenha sido aplicada ao -STABLE após um intervalo razoável de tempo (normalmente algumas semanas), envie ao committer um lembrete educado. . Mova as contribuições de software para [.filename]#src/contrib# na árvore do código fonte. . Tenha certeza que o código disponível em [.filename]#src/contrib# está atualizado. . Compile o sistema (ou apenas uma parte dele) com um nível de debug extra habilitado e corrija a causa dos alertas encontrados. . Corrija os alertas existentes para os ports que ainda fazem coisas ultrapassadas tais como utilizar `gets()` ou incluir [.filename]#malloc.h#. . Se você contribuiu com algum dos ports, e teve que fazer alguma mudança específica para o FreeBSD, envie suas correções de volta aos autores originais (isto tornará sua vida mais fácil quando eles lançarem a próxima versão). . Consiga cópias de padrões formais tais como o POSIX(R). Compare o comportamento do FreeBSD àquele requerido pelo padrão. Se o comportamento diferir, particularmente em pontos sutis ou obscuros da especificação, envie-nos um PR sobre ele. Se você for capaz, descubra como corrigi-lo e inclua um patch em seu PR. Se você acredita que o padrão está errado, peça ao comitê de padrões que considere a pergunta. . Sugira novas tarefas para esta lista! === Trabalhe no banco de dados de PR (relatório de problemas) A https://bugs.FreeBSD.org/search/[Lista de PRs do FreeBSD] mostra todos os relatórios de problemas ativos no momento e os pedidos de melhoria que foram submetidos pelos usuários do FreeBSD. O banco de dados inclui tarefas para programadores e para não-programadores. Consulte os PRs abertos, e veja se algum deles é de seu interesse. Alguns deles podem ser tarefas muito simples que necessitam apenas que um par extra de olhos olhe para eles e confirme que a correção proposta funciona. Outros podem ser muito mais complexos, ou podem nem ter vindo com uma correção. Comece com os PRs que ainda não foram atribuídos a ninguém. Se um PR estiver atribuído a outra pessoa, mas se parecer com algo que você possa cuidar, envie um e-mail para a pessoa encarregada do mesmo e pergunte se você pode trabalhar nele -- ele pode já ter um patch pronto para ser testado, ou você pode discutir novas idéias com ele. === Tarefas em andamento relacionadas a coleção de Ports A coleção de Ports é um trabalho permanente em andamento. Queremos fornecer aos nossos usuários um repositório de software de terceiros fácil de usar, atualizado e de alta qualidade. Precisamos que as pessoas doem parte de seu tempo e esforço para nos ajudar a alcançar esse objetivo. Qualquer um pode se envolver e existem muitas maneiras diferentes de fazer isso. Contribuir para a coleção de ports é uma excelente maneira de ajudar "a devolver algo" ao projeto. Se você está procurando um papel contínuo ou um desafio divertido para um dia chuvoso, nós adoraríamos ter a sua ajuda! Existem várias maneiras fáceis de contribuir para manter a árvore de ports atualizada e em boas condições de funcionamento: * Encontre algum software legal ou útil e link:{porters-handbook}[crie um port] para ele. * Existe um grande número de ports que não possuem nenhum mantenedor. Torne-se um mantenedor e <>. * Se você criou ou adotou um port, esteja ciente <>. * Quando estiver procurando um desafio você poderá <>. === Escolha um dos itens da "`página de idéias`" A https://wiki.freebsd.org/IdeasPage[lista de projetos do FreeBSD e de idéias para voluntários] também está disponível para as pessoas dispostas a contribuir com o projeto FreeBSD. Esta lista é atualizada regularmente e contém itens tanto para programadores e como para não programadores e traz ainda informações sobre cada projeto . [[contrib-how]] == Como Contribuir Contribuições para o sistema geralmente se enquadram em uma das 5 categorias seguintes: [[contrib-general]] === Relatórios de Bugs e Comentários Gerais Uma ideia ou sugestão técnica de interesse _geral_ deverá ser enviada para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-hackers[Lista de discussão de assuntos técnicos do FreeBSD]. Da mesma forma, pessoas com este tipo de interesse (e tolerância para um _alto_ volume de mensagens!) poderão assinar a http://lists.FreeBSD.org/mailman/listinfo/freebsd-hackers[Lista de discussão de assuntos técnicos do FreeBSD]. Veja o link:{handbook}#eresources-mail[Handbook do FreeBSD] para mais informações sobre esta e outras listas. Se você encontrar um bug ou estiver enviando uma mudança específica, por favor relate-o usando o https://bugs.FreeBSD.org/submit/[relatório de envio de bug]. Tente preencher cada campo com do relato de bug. A não ser que exceda 65KB, inclua qualquer correção diretamente no relatório. Se o patch é apropriado para ser aplicado na árvore do código fonte coloque `[PATCH]` no resumo do relatório. Ao incluir patches, _não_ use copiar-e-colar, pois o copiar-e-colar transforma tabs em espaços e os torna inúteis. Quando os patches são muito maiores que 20KB, considere comprimi-los (por exemplo, com man:gzip[1] ou man:bzip2[1]) antes de fazer o envio. Após preencher o relatório, você receberá a confirmação com o número de rastreamento. Guarde este número para que você possa nos atualizar com detalhes sobre do problema. Veja também link:{problem-reports}[este artigo] sobre como escrever bons relatórios de problemas. === Mudanças na Documentação Mudanças na documentação são supervisionadas pela http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc[lista de documentação do projeto FreeBSD]. Por favor veja o link:{fdp-primer}[Manual do Projeto de Documentação do FreeBSD] para instruções completas. Envie contribuições e mudanças (mesmo as pequenas são bem vindas!) utilizando o mesmo método de qualquer outro relatório de bug. === Mudanças no Código Fonte Existente Um acréscimo ou mudança em um código fonte existe é um tema um pouco complicado e depende muito de como você está desatualizado com o estado atual do desenvolvimento do FreeBSD. Existe uma release especial do FreeBSD em andamento conhecida como "FreeBSD-CURRENT" que é disponibilizada de várias maneiras para conveniência dos desenvolvedores que trabalham ativamente no sistema. Veja o link:{handbook}#current-stable[Handbook do FreeBSD] para mais informação sobre como obter e usar o FreeBSD-CURRENT. Trabalhar com versões antigas do código, infelizmente, muitas vezes significa que as suas alterações serão demasiadamente obsoletas ou muito divergentes para possibilitar uma fácil re-integração ao FreeBSD. As possibilidades de que isso ocorra podem ser minimizadas um pouco através da sua inscrição na http://lists.FreeBSD.org/mailman/listinfo/freebsd-announce[lista de distribuição de comunicados oficiais do projeto FreeBSD] e na http://lists.FreeBSD.org/mailman/listinfo/freebsd-current[lista de discussão do FreeBSD-CURRENT], nas quais as discussões sobre o estado atual do sistema ocorrem. Supondo que você consiga obter acesso à uma versão razoavelmente atualizada do código fonte do sistema para basear as suas alterações, o próximo passo é produzir um conjunto de diffs para enviar aos mantenedores do FreeBSD. Isto é feito com o comando man:diff[1]. O formato preferido do man:diff[1] para o envio de um patch, é o formato de saída unificada gerado pelo comando `diff -u`. [source,shell] .... % diff -u oldfile newfile .... ou [source,shell] .... % diff -u -r -N olddir newdir .... deverá gerar um conjunto de diffs unificados para o arquivo de origem informado ou para a hierarquia de diretórios. Consulte o manual do man:diff[1] para maiores informações. Uma vez que você tenha o conjunto de diffs (os quais você pode testar com o comando man:patch[1]), você deve submetê-lo para inclusão no FreeBSD por meio de um relatório de bug. Você _não_ deve enviar os diffs para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-hackers[lista de discussão de assuntos técnicos do FreeBSD] ou eles irão se perder! Agradecemos imensamente a sua submissão (este é um projeto voluntário!); Devido ao alto volume de trabalho, nós podemos não ser capazes de resolvê-lo imediatamente, mas ele permanecerá em nosso banco de dados até que o façamos. Marque a sua submissão incluindo a palavra `[PATCH]` na sinopse do relatório. Se você achar adequado (por ex. você adicionou, deletou ou renomeou arquivos), agrupe as suas mudanças em um arquivo `tar`. Arquivos criados com o man:shar[1] também são bem vindos. Se as suas mudanças são de uma natureza potencialmente sensível, por exemplo, se você não tiver certeza sobre os problemas de direitos autorais que regerão sua distribuição no futuro, envie-as para o Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] ao invés de submetê-las por meio de um relatório de bug. O FreeBSD Core Team mailto:core@FreeBSD.org[core@FreeBSD.org] é formado por um grupo muito pequeno de pessoas as quais cuidam de muitas das tarefas diárias de administração do projeto FreeBSD. Observe que este grupo também é _muito ocupado_ e portanto você só deve enviar um e-mail para eles se for realmente necessário. Por favor, consulte os manuais man:intro[9] e man:style[9] para algumas informações sobre estilo de codificação. Nós apreciaríamos se você estivesse ao menos ciente destas informações antes de submeter o seu código. === Código novo ou pacotes de maior valor agregado No caso de uma contribuição significativa de um trabalho de grande porte, ou a adição de uma nova característica importante ao FreeBSD, torna-se quase sempre necessário que se envie as alterações em um arquivo tar ou então que se faça o upload das mesmas para um servidor WWW ou FTP para que as outras pessoas possam acessá-las. Se você não possui acesso a um servidor WWW ou FTP, pergunte em uma lista de discussão apropriada do FreeBSD se alguém pode hospedar essas alterações para você. Quando se trabalha com grandes quantidades de código, o sensível assunto de direitos autorais invariavelmente vem a tona. O Projeto FreeBSD prefere licenças de software livre tais como BSD ou ISC. Licenças copyleft, como a GPLv2, às vezes são permitidas. A lista completa pode ser encontrada na página sobre a link:https://www.FreeBSD.org/internal/software-license/[política de licenciamento do core team]. === Dinheiro ou Hardware Nós ficamos sempre muito felizes em aceitar doações para agregar a causa do Projeto FreeBSD, em um esforço voluntário como o nosso, um pouco pode significar muito! Doações de hardware também são muito importantes para expandir a nossa lista de periféricos suportados, uma vez que normalmente não temos recursos para comprar estes itens nós mesmos. [[donations]] ==== Doando Dinheiro A Fundação FreeBSD é uma entidade sem fins lucrativos e isenta de impostos, estabelecida com o objetivo de promover os objetivos do Projeto FreeBSD. Como uma entidade 501(c)3, a fundação é isenta de recolher as taxas do governo federal, bem como as do Estado do Colorado. As doações para uma entidade isenta de impostos são frequentemente dedutíveis dos impostos federais. As doações podem ser enviadas através de cheques para: [.address] **** The FreeBSD Foundation + P.O. Box 20247, + Boulder, + CO 80308 + USA **** A Fundação FreeBSD é agora capaz de receber doações através da web com o PayPal. Para fazer uma doação, por favor visite o https://www.freebsdfoundation.org[website a Fundação]. Maiores informações sobre a Fundação FreeBSD podem ser obtidas no documento https://people.FreeBSD.org/~jdp/foundation/announcement.html[A Fundação FreeBSD - Uma introdução]. Para contatar a Fundação por e-mail, escreva para mailto:info@FreeBSDFoundation.org[info@FreeBSDFoundation.org]. ==== Doando Hardware O projeto FreeBSD aceita alegremente doações de hardware para os quais pode encontrar bom uso. Se você estiver interessado em doar componentes de hardware, por favor contate o link:https://www.FreeBSD.org/donations/[Escritório de Relacionamento com Doadores]. [[ports-contributing]] == Contribuindo com a coleção de ports [[adopt-port]] === Adotando um port não mantido ==== Escolhendo um port não mantido Assumir a manutenção de um port sem mantenedor é uma ótima maneira de se envolver. Os ports sem mantenedor só são atualizados e corrigidos quando alguém se oferece para trabalhar neles. Há um grande número de ports não mantidos. É uma boa ideia começar com a adoção de uma port que você usa regularmente. Os ports sem um responsável tem o seu `MAINTAINER` configurado como `ports@FreeBSD.org`. Uma lista com todos os ports nesta situação, bem como os seus erros atuais e os seus relatórios de problemas pode ser visualizada no http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org[Sistema de Monitoração da coleção de ports do FreeBSD]. Alguns ports afetam um grande número de outros devido a dependências e relacionamentos de ports escravos. Geralmente, esperamos que as pessoas tenham alguma experiência antes de se voluntariarem para manter tais ports. Você pode verificar se um port tem ou não dependências ou se outros ports dependem dele consultando o índice mestre de ports chamado [.filename]#INDEX#. (O nome do arquivo varia de acordo com a versão do FreeBSD; por exemplo, [.filename]#INDEX-8#.) Alguns ports têm dependências condicionais que não estão incluídas na construção do [.filename]#INDEX# padrão. Esperamos que você seja capaz de reconhecer estes ports através da analise do arquivo [.filename]#Makefile# de outros ports. ==== Como adotar o port Primeiro, certifique-se de entender quais serão as suas <>. Leia também o link:{porters-handbook}[Porter's Handbook]. _Por favor, não se comprometa com mais do que você acha que pode lidar sem se sobrecarregar._ Você pode solicitar para se tornar o responsável pela manutenção de qualquer port que não esteja sendo mantido por outra pessoa assim que desejar. Basta definir o parâmetro `MAINTAINER` para o seu próprio endereço de e-mail e enviar um PR (Relatório de Problemas) com a alteração. Se o port tiver erros de compilação ou precisar de atualização, você pode aproveitar para incluir quaisquer outras alterações que sejam necessárias neste mesmo PR. Isso irá acelerar o processo pois muitos committers não estão dispostos a atribuir a responsabilidade de manutenção de um port para alguém que não tenha um histórico conhecido com o FreeBSD. O envio de PRs (relatórios de problema) para corrigir erros de compilação ou para atualizar um port é a melhor maneira de estabelecer este histórico. Submeta o seu relatório de problema na categoria `ports` e utilize a classe `change-request`. Um committer irá examinar o seu relatório, confirmará as alterações e, por fim, fechará o relatório. Às vezes, esse processo pode demorar um pouco (os committers também são voluntários). [[maintain-port]] === O desafio para os mantenedores de um port Esta seção lhe dará uma ideia do motivo pelo qual os ports precisam ser mantidos e descreve as responsabilidades de um mantenedor de ports. [[why-maintenance]] ==== Por que os ports requerem manutenção Criar um port é uma tarefa eventual. Mas garantir que um port esteja sempre atualizado e que continue a ser compilado e executado corretamente requer um esforço de manutenção contínuo. Os mantenedores são as pessoas que dedicam parte do seu tempo para atingir esses objetivos. O principal motivo pelo qual a coleção de ports precisa de manutenção é o de trazer os mais recentes e o melhores softwares de terceiros para a comunidade FreeBSD. Um desafio adicional é manter os ports individuais funcionando dentro do framework da coleção de ports à medida que ela evolui. Como mantenedor, você precisará gerenciar os seguintes desafios: * *Novas versões e atualizações de software.* Novas versões e atualizações de software são disponibilizadas o tempo todo para os aplicativos já convertidos, e elas precisam ser incorporadas à Coleção de Ports a fim de prover software atualizado. * *Mudanças nas dependências.* Se forem feitas alterações significativas nas dependências do seu port, talvez seja necessário atualizá-las para que ele continue funcionando corretamente. * *Mudanças que afetem os ports que dependem do seu.* Se outros ports dependerem de um port que você mantém, as mudanças no seu port podem requerer um alinhamento prévio com outros mantenedores. * *Interação com outros usuários, mantenedores e desenvolvedores.* Parte de ser um mantenedor é assumir uma função de suporte. Não existe a expectativa de que você ofereça suporte de uma maneira geral (mas você é bem vindo se quiser fazer isso). O que você deve prover é um ponto de coordenação para as questões específicas do FreeBSD relacionadas aos seus ports. * *Caça aos bugs* Um port pode ser afetado por bugs específicos do FreeBSD. Você precisará investigar, encontrar e consertar estes bugs quando forem reportados. Testar meticulosamente um port para identificar todos os seus possíveis problemas antes que ele seja adicionado à Coleção de Ports é ainda melhor. * *Alterações na infraestrutura e política de ports.* Ocasionalmente os sistemas utilizados para construir os ports e pacotes são atualizados ou uma nova recomendação que afeta a infraestrutura é realizada. Você deverá estar atento a estas mudanças caso seus ports sejam afetados e necessitem de atualização. * *Mudanças no sistema base.* O FreeBSD está em constante desenvolvimento. Mudanças no software, bibliotecas, kernel ou até mesmo mudanças de políticas podem resultar em necessidade de mudança nos ports. ==== Responsabilidades do mantenedor ===== Manter seus ports atualizados Esta seção descreve o processo a ser seguido para manter seus ports atualizados. Esta é uma visão geral. Mais informações sobre a atualização de um port está disponível no link:{porters-handbook}[Porter's Handbook]. [.procedure] . Preste atenção às atualizações + Monitorar os fabricantes upstream em relação a liberação de novas versões, patches e correções de segurança para o software. Listas de discussão de anúncios ou páginas web de noticias sobre o software são úteis para este propósito. Algumas vezes os usuários entrarão em contato com você perguntando quando seu port será atualizado. Se você estiver ocupado com outras atividades ou devido a qualquer outra razão não puder realizar a atualização naquele momento, pergunte se o usuário pode te ajudar enviando uma atualização. + Você também pode receber emails automáticos do `Verificador de Versões de Ports do FreeBSD` informando a você que uma nova versão do disftile do seu port está disponível. Mais informações sobre este sistema (incluindo como deixar de receber seus emails no futuro) serão enviadas na mensagem. . Incorporar mudanças + Quando estiverem disponíves, incorpore as mudanças em seu port. Você precisa ser capaz de gerar um patch entre o port original e o port atualizado. . Revisão e teste + Examine cuidadosamente e teste as suas mudanças ** Compile, instale e teste o seu port em todas plataformas e arquiteturas que você puder. É comum um port funcionar em uma branch ou plataforma e falhar em outra. ** Certifique-se de que as dependências do seu port estão completas. A maneira recomendada de fazer isso é instalando seu próprio ports tinderbox. Consulte a seção sobre <> para mais informações. ** Verifique se a lista de componentes do pacote está atualizada. Isto envolve adicionar novos arquivos e diretórios , bem como remover as entradas sem uso. ** Verifique seu port usando o man:portlint[1] como um guia. Consulte a seção sobre <> para informações importantes sobre o uso do portlint. ** Considere se as mudanças no seu port podem fazer com que outros ports tenham problemas. Se este for o caso, coordene as mudanças com os mantenedores destes ports. Isto é especialmente importante se a sua atualização modifica a versão de uma biblioteca compartilhada; neste caso, os ports afetados precisarão obter no mínimo um incremento no seu `PORTREVISION` para que eles possam ser atualizados automaticamente por ferramentas automatizadas como o portmaster ou o man:portupgrade[1]. . Envie as alterações + Submeta sua atualização enviando um relatório de problema (PR) com uma explicação das alterações e um patch contendo as diferenças entre o port original e a versão atualizada. Por favor, consulte o artigo link:{problem-reports}[Escrevendo um Relatório de Problema para o FreeBSD] para mais informações sobre como escrever um PR realmente bom. + [NOTE] ==== Por favor não submeta um arquivo man:shar[1] do port inteiro, ao invés disso, utilize o comando man:diff[1] `-ruN`. Desta forma, os committers podem ver com mais facilidade exatamente quais alterações estão sendo feitas. Consulte a seção link:{porters-handbook}#port-upgrading[Upgrading] do Porter's Handbook para maiores informações. ==== . Aguarde + Em algum momento, um commiter lidará com o seu PR. Isto pode levar alguns minutos ou pode levar semanas - portanto, seja paciente. . Dê feedback + Se um committer encontrar um problema nas suas alterações, ele provavelmente o encaminhará de volta para você. Uma resposta rápida a este contato irá ajudá-lo a ter o seu PR resolvido mais rapidamente. É muito importante manter o canal de comunicação aberto para agilizar a resolução de qualquer eventual problema. . E finalmente + As suas alterações serão incorporadas na arvore de código fonte e o seu port será atualizado. O PR então será fechado pelo committer. É isso! ===== Certifique-se de que seus ports continuem a ser compilados corretamente Esta seção é sobre a descoberta e a solução de problemas que fazem seus ports deixarem de ser compilados corretamente. O projeto FreeBSD garante o funcionamento da coleção de Ports apenas na branch `-STABLE`. Teoricamente, você deve será capaz de garantir o funcionamento do port ao executá-lo na ultima release de cada branch(já que não se espera que as ABIs mudem), mas se você puder executar a branch, será ainda melhor. Como a maioria das instalações do FreeBSD rodam em máquinas compatíveis com o PC (o que é chamado de arquitetura `i386`), esperamos que você mantenha o port funcionando nesta arquitetura. Nós preferimos que os ports também funcionem de forma nativa na arquitetura `amd64`. É completamente justo pedir ajuda caso você não tenha uma dessas máquinas para fazer seus testes. [NOTE] ==== Os padrões usuais nas falhas para máquinas não-`x86` são que os programadores originais assumiram que, por exemplo, os ponteiros são `int`-s, ou que um compilador gcc mais antigo seria utilizado. Cada vez mais, os autores de aplicativos estão retrabalhando o código das suas aplicações para remover essas suposições - mas se o autor não estiver mantendo ativamente o código, talvez seja necessário que você mesmo faça isso. ==== Estas são as tarefas que você precisa executar para garantir que o seu port pode ser compilado: [.procedure] . Preste atenção para falhas de compilação + Confira o seu e-mail e busque por mensagens do `pkg-fallout@FreeBSD.org` e consulte o http://portscout.FreeBSD.org[scanner de arquivos distfiles] para verificar se algum dos ports que estão falhando na compilação estão desatualizados. . Colete informação + Quando você estiver ciente de um problema, colete informações para ajudá-lo a solucioná-lo. Os erros de compilação relatados pelo `pkg-fallout` são acompanhados por logs que mostram onde a compilação falhou. Se a falha foi reportada para você por um usuário, peça para que ele lhe envie informações que possam ajudar no diagnóstico do problema, tais como: ** Logs de compilação ** Os comandos e opções usados para compilar o port (incluindo opções definidas no [.filename]#/etc/make.conf#) ** Uma lista dos pacotes instalados no sistema como mostrado pelo comando man:pkg-info[8] ** A versão do FreeBSD que ele está executando como mostrado pelo comando man:uname[1] `-a` ** Quando a coleção de ports dele foi atualizada pela última vez ** Quando a árvore de ports e o arquivo [.filename]#INDEX# dele foram atualizados pela última vez . Investigue e encontre uma solução + Infelizmente não existe nenhum processo direto a ser seguido para fazer isso. Porém, lembre-se: se você está emperrado, peça ajuda! A http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[lista de discussão de ports do FreeBSD] é um bom lugar para começar, e os desenvolvedores de upstream são frequentemente muito prestativos. . Envie as alterações + Assim como na atualização de um port, agora você deve incorporar as alterações, revisar, testar e enviar suas alterações em um relatório de problemas (PR) e fornecer feedback, se solicitado. . Envie os patches para os autores upstream + Em alguns casos, você terá que fazer um patch para que um port execute no FreeBSD. Alguns (mas não todos) autores upstream aceitarão incorporar tais patches em seu código na próxima versão. Se eles aceitarem, isto poderá até ajudar os usuários de outros sistemas BSD e talvez evitar um esforço duplicado. Por favor, considere o envio aos autores de quaisquer patches aplicáveis como uma cortesia. ===== Investigue relatórios de bugs e PRs relacionados ao seu port Esta seção é sobre como descobrir e corrigir bugs. Bugs específicos do FreeBSD são causados geralmente por suposições sobre os ambientes de compilação e execução que não se aplicam ao FreeBSD. É pouco provável que você encontre um problema desse tipo, mas se encontrar ele poderá ser mais sutil e difícil de diagnosticar. Estas são as tarefas que você precisa executar para garantir que o seu port continuará funcionando como pretendido: [.procedure] . Responda os relatórios de bugs + Bugs podem ser reportados para você por e-mail através do https://bugs.FreeBSD.org/search/[Sistema de Relatório de Problemas]. Os bugs também podem ser reportados diretamente a você pelos usuários. + Você deve responder os PRs (Relatório de Problemas) e outros relatórios dentro de 14 dias, mas por favor, tente não levar tanto tempo. Tente responder o mais rápido possível, mesmo que seja apenas para dizer que você precisa de mais algum tempo antes de poder trabalhar no PR. + Se você não tiver respondido após 14 dias, qualquer committer poderá efetuar o commit de um PR que você não tenha respondido por meio da regra de `maintainer-timeout`. . Colete informação + Se a pessoa que reportou o bug não tiver fornecido uma correção, você precisará coletar as informações que permitirão gerar uma. + Se o bug for reproduzível, você poderá coletar a maior parte das informações necessárias você mesmo. Caso contrário, peça à pessoa que relatou o bug para coletar as informações para você, tais como: ** Uma descrição detalhada das suas ações, comportamento esperado e comportamento real do aplicativo ** Cópias dos dados de entrada usados para acionar o bug ** Informações sobre seu ambiente de compilação e execução - por exemplo, uma lista de pacotes instalados e a saída de man:env[1] ** Core dumps ** Stack traces . Elimine os relatórios incorretos + Alguns relatórios de erros podem estar incorretos. Por exemplo, o usuário pode ter simplesmente usado de forma errada o programa; ou seus pacotes instalados podem estar desatualizados e precisam ser atualizados. Às vezes, um bug relatado não é específico do FreeBSD. Neste caso relate o bug para os desenvolvedores upstream. Se você for capaz de corrigir o bug, você também poderá criar um patch do port para que a correção seja aplicada antes da próxima versão do upstream. . Encontre uma solução + Tal como acontece com erros de compilação, você precisará encontrar uma correção para o problema. Mais uma vez, lembre-se de perguntar se você estiver emperrado! . Envie ou aprove alterações + Assim como na atualização de um port, agora você deve incorporar alterações, revisar, testar e enviar suas alterações em um PR (ou enviar um follow-up se já existir um PR para o problema). Se outro usuário tiver enviado alterações no PR, você também poderá enviar um follow-up dizendo se aprova ou não as alterações. ===== Forneça Suporte Parte de ser um mantenedor é prover suporte - não para o software em geral - mas para o port e quaisquer peculiaridades e problemas específicos dele no FreeBSD. Os usuários podem entrar em contato com dúvidas, sugestões, problemas e patches. Na maioria das vezes, sua correspondência será específica para o FreeBSD. Ocasionalmente, você pode ter que invocar suas habilidades diplomáticas, e gentilmente, direcionar os usuários que buscam suporte genérico para os recursos apropriados. Com menos frequência você encontrará uma pessoa perguntando por que os `RPMS` não estão atualizados ou como eles podem fazer o software rodar sob o Foo Linux. Aproveite a oportunidade para dizer a eles que o seu port está atualizado (se estiver, é claro!) e sugira que eles experimentem o FreeBSD. Às vezes, os usuários e os desenvolvedores podem decidir que você é uma pessoa ocupada cujo tempo é valioso e farão parte do trabalho para você. Por exemplo, eles podem: * enviar um PR ou lhe enviar patches para atualizar o seu port, * investigar e talvez fornecer uma correção para um PR, ou * caso contrário, enviar alterações para o seu port. Nestes casos, a sua principal obrigação é responder rapidamente. Mais uma vez, o tempo limite para mantenedores não responsivos é de 14 dias. Após esse período, as alterações podem ser aceitas mesmo sem terem sido aprovadas. Eles se deram ao trabalho de fazer isso por você; por favor, tente pelo menos responder prontamente. Em seguida, revise, aprove, modifique ou discuta as alterações com eles o mais rápido possível. Se você puder fazê-los sentir que a contribuição deles é apreciada (e deveria ser), você terá uma chance maior de persuadi-los a fazer mais coisas para você no futuro :-). [[fix-broken]] === Encontre e conserte um port quebrado Existem dois lugares realmente bons para se encontrar um port que precisa de alguma atenção. Você pode usar a https://bugs.freebsd.org/search[interface web] do banco de dados dos Relatório de Problemas para pesquisar e visualizar os PRs não resolvidos. A maioria dos PRs relacionados aos ports são atualizações, mas com um pouco de pesquisa e análise das sinopses você deve encontrar algo interessante para trabalhar (a classe `bug-bug` é um bom lugar para começar). O outro lugar é o http://portsmon.FreeBSD.org/[Sistema de Monitoramento de Ports do FreeBSD]. Em particular, procure por ports sem mantenedores com erros de compilação e por ports marcados com `BROKEN`. Não existe nenhum problema em também enviar alterações para um port com um mantenedor ativo, mas antes lembre-se de consultar o mantenedor para o caso dele já estar trabalhando no problema. Depois de encontrar um bug ou problema, colete informações, investigue e corrija! Se houver um PR existente, de seguimento a ele. Caso contrário, crie um novo PR. Suas alterações serão analisadas e, se tudo estiver OK, elas serão aceitas e incorporadas. [[mortal-coil]] === Quando parar À medida que seus interesses e compromissos mudam, você pode descobrir que não tem mais tempo para continuar com algumas (ou todas) as suas contribuições para a coleção de ports. Tudo bem! Por favor, nos avise se você não estiver mais usando um port ou se não tiver mais tempo ou interesse em ser um mantenedor. Desta forma, podemos seguir em frente e permitir que outras pessoas tentem trabalhar nos problemas existentes com o port sem termos que esperar por sua resposta. Lembre-se, o FreeBSD é um projeto voluntário, então se a manutenção de um port não for mais divertida, provavelmente é hora de deixar alguém fazer isso! De qualquer forma, a Equipe de Gerenciamento da Coleção de Ports (`portmgr`) reserva-se o direito de redefinir o seu status de mantenedor se você não tiver mantido ativamente o seu port durante um determinado período de tempo. (Atualmente, este período é definido como 3 meses.) Com isso, queremos dizer que existem problemas não resolvidos ou atualizações pendentes que não foram tratadas por você durante esse período. [[resources]] === Recursos para mantenedores de ports e contribuidores O link:{porters-handbook}[Porter's Handbook] é o seu Guia de Mochileiro para o sistema de ports. Mantenha-o à mão! O artigo link:{problem-reports}[Escrevendo um relatório de problemas para o FreeBSD] descreve como melhor formular e enviar um PR. Em 2005, foram submetidos mais de onze mil relatórios de problemas relacionados aos ports! Ao seguir as boas práticas descritas neste artigo você nos ajudará a reduzir em muito o tempo necessário para lidar com seus PRs. O https://bugs.freebsd.org/bugzilla/query.cgi[Banco de dados de problemas reportados]. O http://portsmon.FreeBSD.org/[Sistema de Monitoramento de Ports do FreeBSD] pode mostrar informações cruzadas sobre os ports, tais como erros de compilação e relatórios de problemas. Se você é um mantenedor, você pode usá-lo para verificar o status de compilação dos seus ports. Como colaborador, você pode usá-lo para encontrar ports quebrados e ports sem um mantenedor ativo que precisam ser consertados. O http://portscout.FreeBSD.org[scanner de arquivos distfile] da coleção de ports do FreeBSD pode lhe mostrar os ports para os quais os arquivos distfiles não estão disponíveis. Você pode utilizá-lo para verificar seus próprios ports ou para encontrar ports que precisam ter seu `MASTER_SITES` atualizado. O uso do package:ports-mgmt/poudriere[] é a maneira mais completa de testar um port durante todo o ciclo de instalação, empacotamento e desinstalação. A documentação está localizada no https://github.com/freebsd/poudriere[Repositório do poudriere no github] O man:portlint[1] é uma aplicação que pode ser utilizada para verificar se o seu port está em conformidade com muitas diretrizes importantes de estilo e função. O portlint é um aplicativo heurístico simples, portanto você deve usá-lo __apenas como um guia__. Se o portlint sugerir alterações que não sejam razoáveis, consulte o link:{porters-handbook}[Porter's Handbook] ou peça conselhos. A http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports[Lista de discussão de ports do FreeBSD ] é destinada para discussões gerais relacionadas aos ports. É um bom lugar para pedir ajuda. Você pode se https://lists.freebsd.org/mailman/listinfo[inscrever, ler e pesquisar os arquivos da lista]. Ler os arquivos da http://lists.FreeBSD.org/mailman/listinfo/freebsd-ports-bugs[Lista de discussão sobre bugs dos ports do FreeBSD] e as http://lists.FreeBSD.org/mailman/listinfo/svn-ports-head[mensagens de commit no SVN da árvore de ports para head/] também pode ser interessante. [[ideas-contributing]] == Começando em outras áreas Procurando por algo interessante para começar, e que não foi mencionado em outras partes deste artigo? O Projeto FreeBSD tem várias páginas Wiki contendo áreas nas quais novos colaboradores podem ter ideias sobre como começar. A página https://wiki.freebsd.org/JuniorJobs[Júnior Jobs] tem uma lista de projetos que podem ser de interesse para pessoas que estão apenas começando no FreeBSD, e querem trabalhar em coisas interessantes para molhar os pés. A https://wiki.freebsd.org/IdeasPage[Página de Idéias] contém várias coisas "legais" ou "interessantes" para se trabalhar no Projeto. diff --git a/documentation/content/pt-br/articles/filtering-bridges/_index.adoc b/documentation/content/pt-br/articles/filtering-bridges/_index.adoc index 565e708eaa..895bac5c38 100644 --- a/documentation/content/pt-br/articles/filtering-bridges/_index.adoc +++ b/documentation/content/pt-br/articles/filtering-bridges/_index.adoc @@ -1,226 +1,236 @@ --- title: Pontes de Filtragem (Filtering Bridges) authors: - author: Alex Dupre email: ale@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "3com", "intel", "general"] --- = Pontes de Filtragem (Filtering Bridges) :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Geralmente, é útil dividir uma rede física (como uma Ethernet) em dois segmentos separados, sem precisar criar sub-redes, e usar um roteador para vinculá-los. O dispositivo que conecta as duas redes dessa maneira é chamado de ponte (bridge). Um sistema FreeBSD com duas interfaces de rede é suficiente para atuar como uma ponte. Uma ponte funciona examinando os endereços do nível MAC (endereços Ethernet) dos dispositivos conectados a cada uma de suas interfaces de rede e encaminhando o tráfego entre as duas redes apenas se a origem e o destino estiverem em diferentes segmentos. Sob muitos pontos de vista, uma ponte é semelhante a um switch Ethernet com apenas duas portas. ''' toc::[] [[filtering-bridges-why]] == Por que usar uma ponte de filtragem? Cada vez mais frequentemente, graças aos custos reduzidos de conexões de banda larga à Internet (xDSL) e também devido à redução de endereços IPv4 disponíveis, muitas empresas estão conectadas à Internet 24 horas por dia e com poucos (às vezes nem mesmo 2) endereços IP. Nestas situações, geralmente é desejável ter um firewall que filtre o tráfego de entrada e de saída de e para a Internet, mas uma solução de filtragem de pacotes baseada em roteador pode não ser aplicável, quer seja devido a problemas de sub-redes, quer seja porque o roteador é de propriedade do provedor de conectividade (ISP), ou porque ele não suporta tais funcionalidades. Nestes cenários, o uso de uma ponte de filtragem é altamente recomendado. Um firewall baseado em uma ponte de filtragem pode ser configurado e inserido entre o roteador xDSL e seu hub/switch Ethernet sem causar nenhum problema de numeração IP. [[filtering-bridges-how]] == Como instalar Adicionar funcionalidades de bridge a um sistema FreeBSD não é difícil. Desde a versão 4.5 é possível carregar tais funcionalidades como módulos ao invés de ter que reconstruir o kernel, simplificando bastante o procedimento. Nas subseções seguintes, explicarei as duas formas de instalação. [IMPORTANT] ==== _Não_ siga as duas instruções: um procedimento _exclui_ o outro. Selecione a melhor opção de acordo com suas necessidades e habilidades. ==== Antes de continuar, certifique-se de ter pelo menos duas placas Ethernet compatíveis com o modo promíscuo para recepção e transmissão, pois elas devem ser capazes de enviar pacotes Ethernet com qualquer endereço, não apenas o deles. Além disso, para ter uma boa taxa de transferência, as placas devem ser placas do barramento PCI. As melhores opções ainda são as Intel EtherExpress(TM) Pro, seguido pela série 3Com(R) 3c9xx. Para simplificar a configuração do firewall, pode ser útil ter duas placas de diferentes fabricantes (usando drivers diferentes) para distinguir claramente qual interface está conectada ao roteador e qual está conectada à rede interna. [[filtering-bridges-kernel]] === Configuração do Kernel Então você decidiu usar o método de instalação mais antigo, e também o mais bem testado. Para começar, você precisa adicionar as seguintes linhas ao seu arquivo de configuração do kernel: [.programlisting] .... options BRIDGE options IPFIREWALL options IPFIREWALL_VERBOSE .... A primeira linha adiciona o suporte para o serviço de ponte (bridge), a segunda adiciona o suporte ao firewall e a terceira é referente as funções de registro do firewall. Agora é necessário compilar e instalar o novo kernel. Você pode encontrar instruções detalhadas na seção link:{handbook}#kernelconfig-building[Compilando e Instalando um Kernel Personalizado] do Handbook do FreeBSD. [[filtering-bridges-modules]] === Carregamento de módulos Se você escolheu usar o método de instalação mais novo e mais simples, a única coisa a fazer agora é adicionar a seguinte linha ao [.filename]#/boot/loader.conf#: [.programlisting] .... bridge_load="YES" .... Desta forma, durante a inicialização do sistema, o módulo [.filename]#bridge.ko# será carregado junto com o kernel. Não é necessário adicionar uma linha semelhante para o módulo [.filename]#ipfw.ko#, pois ele será carregado automaticamente após a execução das etapas na seção a seguir. [[filtering-bridges-finalprep]] == Preparação final Antes de reinicializar para carregar o novo kernel ou os módulos requeridos (de acordo com o método de instalação escolhido anteriormente), você deve fazer algumas alterações no arquivo de configuração [.filename]#/etc/rc.conf#. A regra padrão do firewall é rejeitar todos os pacotes IP. Inicialmente vamos configurar um firewall `open` (aberto), a fim de verificar sua operação sem qualquer problema relacionado à filtragem de pacotes (no caso de você executar este procedimento remotamente, tal configuração evitará que você permaneça isolado da rede). Coloque estas linhas no [.filename]#/etc/rc.conf#: [.programlisting] .... firewall_enable="YES" firewall_type="open" firewall_quiet="YES" firewall_logging="YES" .... A primeira linha ativará o firewall (e carregará o módulo [.filename]#ipfw.ko# se ele não estiver compilado no kernel), a segunda irá configurá-lo no modo `open` (como explicado em [.filename]#/etc/rc.firewall#), a terceira para não mostrar o carregamento de regras e a quarta para ativar o suporte aos logs. Sobre a configuração das interfaces de rede, a maneira mais usada é atribuir um IP a apenas uma das placas de rede, mas a ponte funcionará igualmente, mesmo que ambas as interfaces ou nenhuma tenha um IP configurado. No último caso (IP-less) a máquina bridge ficará ainda mais oculta, e também inacessível pela rede: para configurá-la será necessário efetuar o login a partir do console ou através de uma terceira interface de rede separada da ponte. Às vezes, durante a inicialização do sistema, alguns programas exigem acesso à rede, digamos, para resolução de nomes de domínio: neste caso, é necessário atribuir um IP à interface externa (aquela conectada à Internet, onde o servidor DNS se encontra), uma vez que a ponte será ativada no final do procedimento de inicialização. Isso significa que a interface [.filename]#fxp0# (no nosso caso) deve ser mencionada na seção ifconfig do arquivo [.filename]#/etc/rc.conf#, enquanto o [.filename]#xl0# não é. Atribuir um IP a ambas as placas de rede não faz muito sentido, a menos que, durante o procedimento de inicialização, os aplicativos acessem os serviços em ambos os segmentos de Ethernet. Há outra coisa importante a saber. Ao executar o IP sobre Ethernet, existem dois protocolos Ethernet em uso: um é o IP, o outro é o ARP. O ARP faz a conversão do endereço IP de um host em seu endereço Ethernet (camada MAC). Para permitir a comunicação entre dois hosts separados pela ponte, é necessário que a ponte envie pacotes ARP. Esse protocolo não está incluído na camada IP, uma vez que ele existe apenas com IP sobre Ethernet. O firewall do FreeBSD filtra exclusivamente na camada IP e, portanto, todos os pacotes não-IP (ARP incluso) serão encaminhados sem serem filtrados, mesmo que o firewall esteja configurado para não permitir nada. Agora é hora de reiniciar o sistema e usá-lo como antes: haverá algumas novas mensagens sobre a ponte e o firewall, mas a ponte não será ativada e o firewall, estando no modo `open`, não evitará operações. Se houver algum problema, você deve resolvê-los agora antes de prosseguir. [[filtering-bridges-enabling]] == Habilitando a ponte Neste ponto, para habilitar a ponte, você tem que executar os seguintes comandos (tendo a perspicácia para substituir os nomes das duas interfaces de rede [.filename]#fxp0# e [.filename]#xl0# com as suas próprias): [source,shell] .... # sysctl net.link.ether.bridge.config=fxp0:0,xl0:0 # sysctl net.link.ether.bridge.ipfw=1 # sysctl net.link.ether.bridge.enable=1 .... A primeira linha especifica quais interfaces devem ser ativadas pela ponte, a segunda habilitará o firewall na ponte e, finalmente, a terceira habilitará a ponte. [NOTE] ==== Se você tem o FreeBSD 5.1-RELEASE ou anterior, as variáveis do sysctl são escritas de forma diferente. Veja man:bridge[4] para detalhes. ==== Neste ponto você deve ser capaz de inserir a máquina entre dois conjuntos de hosts sem comprometer quaisquer habilidades de comunicação entre eles. Em caso afirmativo, o próximo passo é adicionar as partes `net.link.ether.bridge._[blah]_=_[blah]_` dessas linhas ao arquivo [.filename]#/etc/sysctl.conf#, para que eles sejam executados na inicialização. [[filtering-bridges-ipfirewall]] == Configurando o Firewall Agora é hora de criar seu próprio arquivo com regras de firewall personalizadas, a fim de proteger a rede interna. Haverá alguma complicação em fazer isso porque nem todas as funcionalidades do firewall estão disponíveis em pacotes em ponte. Além disso, há uma diferença entre os pacotes que estão sendo encaminhados e os pacotes que estão sendo recebidos pela máquina local. Em geral, os pacotes de entrada passam pelo firewall apenas uma vez, não duas vezes, como é normalmente o caso; na verdade eles são filtrados somente após o recebimento, portanto, as regras que usam `out` ou `xmit` nunca darão match. Pessoalmente, eu uso `in via` que é uma sintaxe antiga, mas uma que tem sentido quando você a lê. Outra limitação é que você está restrito a usar somente comandos `pass` ou `drop` para os pacotes filtrados por uma ponte. Coisas sofisticadas como `divert`, `forwar` ou `reject` não estão disponíveis. Essas opções ainda podem ser usadas, mas apenas no tráfego para ou a partir da própria máquina ponte (se ela tiver um endereço IP). O conceito de filtragem stateful é novo no FreeBSD 4.0. Esta é uma grande melhoria para o tráfego UDP, que normalmente é um pedido que sai, seguido pouco depois por uma resposta com exatamente o mesmo conjunto de endereços IP e números de porta (mas com origem e destino invertidos, é claro). Para firewalls que não possuem manutenção de estado, quase não há como lidar com esse tipo de tráfego como uma sessão única. Mas com um firewall que pode "lembrar" de um pacote UDP de saída e, nos próximos minutos, permitir uma resposta, o manuseio de serviços UDP é trivial. O exemplo a seguir mostra como fazer isso. É possível fazer a mesma coisa com pacotes TCP. Isso permite que você evite alguns ataques de negação de serviço e outros truques desagradáveis, mas também faz com que sua tabela de estado cresça rapidamente em tamanho. Vamos ver um exemplo de configuração. Note primeiro que no topo do [.filename]#/etc/rc.firewall# já existem regras padrão para a interface de loopback [.filename]#lo0#, então não devemos mais precisar delas. Regras customizadas devem ser colocadas em um arquivo separado (digamos, [.filename]#/etc/rc.firewall.local#) e carregadas na inicialização do sistema, modificando a linha de [.filename]#/etc/rc.conf# onde definimos o firewall `open`: [.programlisting] .... firewall_type="/etc/rc.firewall.local" .... [IMPORTANT] ==== Você tem que especificar o caminho __completo__, caso contrário ele não será carregado com o risco de permanecer isolado da rede. ==== Para nosso exemplo, imagine ter a interface [.filename]#fxp0# conectada para o exterior (Internet) e a [.filename]#xl0# para o interior (LAN). A máquina ponte tem o IP `1.2.3.4` (não é possível que o seu ISP possa lhe dar um endereço assim, mas para nosso exemplo ele é bom). [.programlisting] .... # Things that we have kept state on before get to go through in a hurry add check-state # Throw away RFC 1918 networks add drop all from 10.0.0.0/8 to any in via fxp0 add drop all from 172.16.0.0/12 to any in via fxp0 add drop all from 192.168.0.0/16 to any in via fxp0 # Allow the bridge machine to say anything it wants # (if the machine is IP-less do not include these rows) add pass tcp from 1.2.3.4 to any setup keep-state add pass udp from 1.2.3.4 to any keep-state add pass ip from 1.2.3.4 to any # Allow the inside hosts to say anything they want add pass tcp from any to any in via xl0 setup keep-state add pass udp from any to any in via xl0 keep-state add pass ip from any to any in via xl0 # TCP section # Allow SSH add pass tcp from any to any 22 in via fxp0 setup keep-state # Allow SMTP only towards the mail server add pass tcp from any to relay 25 in via fxp0 setup keep-state # Allow zone transfers only by the slave name server [dns2.nic.it] add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state # Pass ident probes. It is better than waiting for them to timeout add pass tcp from any to any 113 in via fxp0 setup keep-state # Pass the "quarantine" range add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state # UDP section # Allow DNS only towards the name server add pass udp from any to ns 53 in via fxp0 keep-state # Pass the "quarantine" range add pass udp from any to any 49152-65535 in via fxp0 keep-state # ICMP section # Pass 'ping' add pass icmp from any to any icmptypes 8 keep-state # Pass error messages generated by 'traceroute' add pass icmp from any to any icmptypes 3 add pass icmp from any to any icmptypes 11 # Everything else is suspect add drop log all from any to any .... Aqueles de vocês que já configuraram firewalls antes podem notar algumas coisas que estão faltando. Em particular, não há regras anti-spoofing, na verdade nós _não_ adicionamos: [.programlisting] .... add deny all from 1.2.3.4/8 to any in via fxp0 .... Ou seja, dropar os pacotes que estão vindo do lado de fora dizendo ser da nossa rede. Isso é algo que você normalmente faria para ter certeza de que alguém não tentaria escapar do filtro de pacotes, gerando pacotes nefastos que parecem ser de dentro. O problema é que existe _pelo menos_ um host na interface externa que você não deseja ignorar: o roteador. Mas geralmente ISP tem anti-spoofs em seu roteador, então não precisamos nos incomodar muito. A última regra parece ser uma duplicata exata da regra padrão, ou seja, não deixa passar nada que não seja especificamente permitido. Mas há uma diferença: todo tráfego suspeito será registrado. Existem duas regras para passar o tráfego SMTP e o do DNS para o servidor de e-mail e o servidor de nomes, se você os tiver. Obviamente, todo o conjunto de regras deve ser definido de acordo com as suas preferências pessoais, isso é apenas um exemplo específico (o formato da regra é descrito com precisão na página de manual do man:ipfw[8]). Note que, para que o "relay" e o "ns" funcionem, as pesquisas de serviço de nomes devem funcionar _antes_ da ponte ser ativada. Este é um exemplo de quando você precisa ter certeza de que definiu o IP na placa de rede correta. Como alternativa, é possível especificar o endereço IP em vez do nome do host (necessário se a máquina não tiver IP). As pessoas que estão acostumadas a configurar firewalls provavelmente também estão acostumadas a ter uma regra `reset` ou `forward` para pacotes ident (TCP porta 113). Infelizmente, esta não é uma opção aplicável com a ponte, então o melhor é simplesmente passá-las ao seu destino. Enquanto essa máquina de destino não estiver executando um daemon ident, isso é relativamente inofensivo. A alternativa é descartar as conexões na porta 113, o que criará alguns problemas com serviços como por exemplo o IRC (o probe do ident irá dar timeout). A única outra coisa que é um pouco estranha e que você pode ter notado é que existe uma regra para deixar a máquina ponte falar, e outra para os hosts internos. Lembre-se que isso ocorre porque os dois conjuntos de tráfego terão caminhos diferentes através do kernel e do filtro de pacotes. A rede interna passará pela ponte, enquanto a máquina local usará a pilha IP normal para falar. Assim, as duas regras lidam com casos diferentes. As regras `in via fxp0` funcionam nos dois caminhos. Em geral, se você usar as regras `in via` em todo o filtro, precisará abrir uma exceção para pacotes gerados localmente, porque eles não vieram em nenhuma de nossas interfaces. [[filtering-bridges-contributors]] == Colaboradores Muitas partes deste artigo foram tiradas, atualizadas e adaptadas de um texto antigo sobre pontes, editado por Nick Sayer. Um par de inspirações deve-se a uma introdução sobre pontes de Steve Peterson. Um grande obrigado ao Luigi Rizzo pela implementação do código de ponte (bridge) no FreeBSD e pelo tempo que ele dedicou a mim respondendo a todas as minhas perguntas relacionadas. Agradeço também a Tom Rhodes, que olhou para o meu trabalho de tradução do italiano (a língua original deste artigo) para o inglês. diff --git a/documentation/content/pt-br/articles/freebsd-questions/_index.adoc b/documentation/content/pt-br/articles/freebsd-questions/_index.adoc index c20ca695dc..15162879bf 100644 --- a/documentation/content/pt-br/articles/freebsd-questions/_index.adoc +++ b/documentation/content/pt-br/articles/freebsd-questions/_index.adoc @@ -1,235 +1,245 @@ --- title: Como obter os melhores resultados da lista de email FreeBSD-questions authors: - author: Greg Lehey email: grog@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "microsoft", "opengroup", "qualcomm", "general"] --- = Como obter os melhores resultados da lista de email FreeBSD-questions :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este documento provê informação para pessoas que desejam mandar um email para a lista de discussão FreeBSD-questions. Avisos e dicas são disponibilizados para maximizar a chance do leitor de receber respostas úteis. Esse documento é regularmente postado na lista de email FreeBSD-questions. ''' toc::[] == Introdução A `FreeBSD-questions` é uma lista de emails mantida pelo Projeto FreeBSD para ajudar pessoas que tenham questões sobre o uso normal do FreeBSD. Outra lista, a `FreeBSD-hackers`, aborda questões mais avançadas tais como desenvolvimentos futuros. [NOTE] ==== O termo "hacker" não tem nada a ver com invasão de computadores alheios.O termo correto para este tipo de atividade é "cracker", mas a mídia popular e a imprensa não tomou conhecimento deste fato ainda. Os hackers do FreeBSD fortemente desaprovam a atividade de cracking e não se envolvem neste tipo de atividades. Para uma descrição mais abrangente sobre hackers, veja o link de Eric Raymond's http://www.catb.org/~esr/faqs/hacker-howto.html[How To Become A Hacker] ==== Esta é uma mensagem padrão com vistas a ajudar tanto quem busca ajuda na lista FreeBSD-questions (os "novatos"), quanto quem responde às questões (os "hackers"). Inevitavelmente sempre existe algum atrito, o qual deriva dos diferentes pontos de vista dos dois grupos. Os novatos acusam os hackers de serem arrogantes, orgulhosos e não ajudarem, enquanto os hackers acusam os novatos de serem burros, incapazes de lerem textos em simples Português, e esperarem que tudo seja dado a eles em uma bandeja de prata. Claro que há algum elemento de verdade em cada um dos discursos, mas normalmente estes pontos de vista são frutos de algum tipo de frustração. Nesse documento, eu desejo fazer algo para aliviar essa frustração e ajudar todos a obterem melhores resultados da FreeBSD-questions. Na próxima seção, eu recomendo como enviar uma pergunta; depois disso, veremos como responder a uma. == Como se Inscrever na FreeBSD-questions A FreeBSD-questions é uma lista de email, então você precisa de uma conta de email. Aponte o seu navegador Web para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions[página de informações da lista FreeBSD-questions]. Na seção entitulada "Inscrevendo-se na freebsd-questions" preencha o campo "Seu endereço de email"; os demais campos são opcionais. [NOTE] ==== O campo para senha no formulário de inscrição proporciona somente uma segurança moderada, mas deve evitar que outros enviem mensagens usando sua conta. _Não use uma senha importante para você_ pois ela eventualmente poderá ser enviada para você por email em texto plano. ==== Você receberá uma mensagem de confirmação do mailman; siga as instruções incluídas na mensagem para completar sua inscrição. Finalmente, quando você receber a mensagem de "Boas-vindas" do mailman informando os detalhes da lista e a senha para acesso à área restrita, __por favor salve-a__. Se você algum dia desejar sair da lista, você necessitará das informações contidas nesta mensagem. Veja a próxima seção para mais detalhes. == Como sair da lista FreeBSD-questions Quando você se inscreve na lista FreeBSD-questions, você recebe uma mensagem de boas-vindas do mailman. Nessa mensagem, dentre outras coisas, é informado como sair da lista. Segue um exemplo desta mensagem: .... Bem-vindo à lista de discussão freebsd-questions@freebsd.org! Para enviar uma mensagem para esta lista, mande seu email para: freebsd-questions@freebsd.org Informações gerais sobre a lista estão em: https://lists.freebsd.org/mailman/listinfo/freebsd-questions Se você eventualmente desejar sair da lista ou alterar suas opções (ex. mudar para o modo resumo diário ou para sair dele, mudar senha, etc.) visite sua página de inscrição em: https://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de Você pode também fazer estes ajustes por email, enviando uma mensagem para: freebsd-questions-request@freebsd.org com a palavra 'help' no campo assunto ou no corpo da mensagem (não inclua as aspas), e você receberá uma mensagem com instruções. Você precisa saber sua senha para alterar as opções (incluindo alterar a própria senha) ou para sair da lista. Ela é: 12345 Normalmente, Mailman lembrará você de sua senha na lista do freebsd.org uma vez por mês, mas você pode desabilitar isto se assim desejar. Este lembrete também incluirá instruções de como sair da lista ou alterar suas preferências de conta. Há também um botão na sua página de opções que enviará sua senha atual para você. .... A partir da URL informada na sua mensagem de "Boas-vindas" você pode visitar a "Página de gerenciamento da sua conta" e fazer uma requisição para "Sair" da lista FreeBSD-questions. Uma mensagem de confirmação será enviada para você pelo mailman; siga as instruções contidas na mensagem para finalizar o desligamento da lista. Se você já fez isso, e ainda não conseguiu entender o que está havendo, mande uma mensagem para mailto:freebsd-questions-request@FreeBSD.org[freebsd-questions-request@FreeBSD.org], e eles irão resolver as coisas para você. _Não envie_ uma mensagem para a FreeBSD-questions: eles não podem ajudá-lo. == Devo perguntar na lista `-questions` ou na `-hackers`? Duas listas de discussão abordam questões gerais sobre o FreeBSD, `FreeBSD-questions` e `FreeBSD-hackers`. Em alguns casos, não é realmente claro para qual lista você deve enviar sua pergunta. Entretanto, os seguintes critérios devem ajudar em 99% de todas as perguntas: . Se a questão é genérica, pergunte na `FreeBSD-questions`. Como exemplo temos questões sobre a instalação do FreeBSD ou o uso de uma ferramenta doUNIX(R). . Se você acredita que a pergunta está relacionada a um bug, mas não tem certeza disso, ou você não sabe como pesquisar sobre isso, mande a mensagem para a lista `FreeBSD-questions`. . Se você acredita que a pergunta está relacionada com um bug, e você tem _certeza_ que é um bug (por exemplo, você pode apontar o lugar do código onde isso acontece, e você poder ter uma correção para o problema), então envie a mensagem para a lista `FreeBSD-hackers`. . Se a questão envolve melhoramentos no FreeBSD, e você pode sugerir em como isto pode ser implementado, então mande a menssagem para a lista `FreeBSD-hackers`. Há também uma boa quantidade de link:{handbook}#eresources-mail[listas de email especializadas], que atendem interesses mais específicos. O critério acima ainda se aplica, e é interessante que você o siga, pois há mais chance de você obter melhores resultados desta forma. == Antes de Enviar uma Pergunta Você pode (e deve) fazer algumas coisas você mesmo antes de fazer uma pergunta em uma das listas de discussão: * Tente resolver o problema sozinho. Se você enviar uma pergunta que demonstre que você tentou resolver o problema, sua mensagem vai normalmente atrair mais atenção de uma forma positiva das pessoas que a leram. Tentar resolver o problema sozinho também vai aumentar seu entendimento do FreeBSD, e eventualmente vai proporcionar conhecimento para você poder responder perguntas de outros usuários das listas e também ajudar. * Leia as páginas dos manuais, e a documentação do FreeBSD (tanto a instalada em [.filename]#/usr/doc# ou a versão acessível via Web em http://www.FreeBSD.org[http://www.FreeBSD.org]), especialmente o link:{handbook}[handbook] e o link:{faq}[FAQ]. * Procure e/ou pesquise nos arquivos da lista de discussão, para verificar se a sua pergunta ou uma pergunta semelhante já foi feita (e possivelmente respondida) antes na lista. Você pode navegar e/ou pesquisar os arquivos da lista de discussão em https://www.FreeBSD.org/mail[https://www.FreeBSD.org/mail] e https://www.FreeBSD.org/search/#mailinglists[https://www.FreeBSD.org/search/#mailinglists], respectivamente. Isso pode ser feito em outros sites da Web, como por exemplo, em http://marc.theaimsgroup.com[http://marc.theaimsgroup.com]. * Use um mecanismo de pesquisa como o http://www.google.com[Google] ou http://www.yahoo.com[Yahoo] para encontrar respostas para a sua pergunta. == Como Enviar uma Pergunta Quando for enviar uma pergunta para a lista FreeBSD-questions, considere as seguintes diretivas: * Lembre-se que ninguém é pago por responder uma pergunta sobre o FreeBSD. Eles fazem isso por vontade própria. Você pode influenciar positivamente esse livre arbítrio enviando uma pergunta bem formulada, fornecendo o máximo possível de informações relevantes. Você pode influenciar esse livre arbítrio negativamente enviando uma pergunta incompleta, ilegível ou grosseira. É perfeitamente possível enviar uma mensagem para a lista FreeBSD-questions e não obter uma resposta, mesmo que você siga estas regras. É muito mais fácil não obter uma resposta se você não o fizer. No restante deste documento, veremos como tirar o máximo proveito de uma pergunta para a FreeBSD-questions. * Nem todo mundo que responde as perguntas sobre o FreeBSD lê todas as mensagens: eles olham para o assunto e decidem se isso lhes interessa. Claramente, é do seu interesse especificar um assunto. Assuntos como "Problema do FreeBSD" ou "Ajuda" não são suficientes. Se você não fornecer nenhum assunto, muitas pessoas não se incomodarão em lê-lo. Se o seu assunto não for específico o suficiente, as pessoas que podem responder sua pergunta podem não ler sua mensagem. * Formate a sua mensagem para que ela fique legível e, POR FAVOR, NÃO GRITE !!!!! Nós apreciamos que muitas pessoas não falam inglês como sua primeira língua, e tentamos fazer concessões para isso, mas é realmente doloroso tentar ler uma mensagem escrita com erros de digitação ou sem quebras de linha. + Não subestime o efeito que uma mensagem de correio mal formatada tem, não apenas na lista de discussão FreeBSD-questions. Sua mensagem de e-mail é o que todas as pessoas vêem de você, e se estiver mal formatada, uma linha por parágrafo, mal grafada ou cheia de erros, isso dará às pessoas uma má impressão sobre você. + Muitas mensagens mal formatadas vêm de http://www.lemis.com/email.html[clientes de email ruins ou mal-configurados]. Os seguintes clientes de email são conhecidos por enviar mensagens mal formatadas sem que você saiba sobre elas: ** Eudora(R) ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook(R) + Tente não usar MIME: muitas pessoas usam clientes de email que não se dão muito bem com MIME. * Verifique se seu horário e fuso horário estão definidos corretamente. Isso pode parecer um pouco bobo, já que sua mensagem ainda será distribuída, mas muitas das pessoas que você está tentando alcançar recebem várias centenas de mensagens por dia. Eles frequentemente classificam as mensagens recebidas por assunto e por data, e se a sua mensagem não vem antes da primeira resposta, eles podem assumir que eles perderam e não se darão ao trabalho de procurar. * Não inclua perguntas não relacionadas na mesma mensagem. Em primeiro lugar, uma mensagem longa tende a assustar as pessoas e, em segundo lugar, é mais difícil conseguir que todas as pessoas que podem responder a todas as perguntas leiam a mensagem. * Especifique o máximo de informação possível. Essa é uma área difícil, precisamos expandir e detalhar melhor quais informações você precisa enviar, mas aqui está um começo: ** Em quase todos os casos, é importante conhecer a versão do FreeBSD que você está executando. Este é particularmente o caso do FreeBSD-CURRENT, onde você também deve especificar a data do código fonte, embora, obviamente, você não deva enviar perguntas sobre -CURRENT para a FreeBSD-questions. ** Com qualquer problema que _possa_ ser relacionado a hardware, informe-nos sobre o seu hardware. Em caso de dúvida, suponha que seja possível que seja hardware. Que tipo de CPU você está usando? Quão rápido? Qual placa-mãe? Quanta memória? Quais periféricos? + Há uma chamada de julgamento aqui, é claro, mas a saída do comando man:dmesg[8] frequentemente pode ser muito útil, já que não apenas informa qual hardware você está executando, mas qual a versão do FreeBSD também. ** Se você receber mensagens de erro, não diga "eu recebo mensagens de erro", diga (por exemplo) " eu recebo a mensagem de erro 'No route to host'". ** Se o seu sistema entrar em panic, não diga "Meu sistema entrou em panic", diga (por exemplo) "meu sistema entrou em panic com a mensagem 'free vnode isn't'". ** Se você tiver dificuldades em instalar o FreeBSD, por favor, nos diga qual hardware você possui. Em particular, é importante conhecer os IRQs e os endereços de I/O das placas instaladas em sua máquina. ** Se você tiver dificuldade em executar o PPP, descreva a configuração. Qual versão do PPP você usa? Que tipo de autenticação você tem? Você tem um endereço IP estático ou dinâmico? Que tipo de mensagens você recebe no arquivo de log? * Muitas das informações que você precisa fornecer são a saída de programas, como man:dmesg[8], ou mensagens do console, que geralmente aparecem em [.filename]#/var/log/messages#. Não tente copiar essa informação digitando-a novamente; é um sofrimento real e você está fadado a cometer um erro. Para enviar o conteúdo do arquivo de log, faça uma cópia do arquivo e use um editor para reduzir as informações apenas ao que for relevantes ou copie e cole na sua mensagem. Para a saída de programas como man:dmesg[8], redirecione a saída para um arquivo e inclua-o. Por exemplo, + [source,shell] .... % dmesg > /tmp/dmesg.out .... + Isto redireciona a informação para o arquivo [.filename]#/tmp/dmesg.out#. * Se você fizer tudo isso e ainda não obtiver uma resposta, pode haver outras razões. Por exemplo, o problema é tão complicado que ninguém sabe a resposta, ou a pessoa que sabe a resposta estava offline. Se você não obtiver uma resposta depois de, digamos, uma semana, pode ajudar se você reenviar a mensagem. Se você não obtiver uma resposta para sua segunda mensagem, provavelmente não obterá uma deste fórum. Reenviar a mesma mensagem de novo e de novo só o tornará impopular. Para resumir, vamos supor que você saiba a resposta para a seguinte pergunta (sim, é a mesma em cada caso). Você escolhe qual destas duas perguntas você estaria mais preparado para responder: .Mensagem 1 [example] ==== .... Subject: HELP!!?!?? I just can't get hits damn silly FereBSD system to workd, and Im really good at this tsuff, but I have never seen anythign sho difficult to install, it jst wont work whatever I try so why don't you guys tell me what I doing wrong. .... ==== .Mensagem 2 [example] ==== .... Subject: Problems installing FreeBSD I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot of difficulty installing it. I have a 66 MHz 486 with 16 MB of memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball disk and a Toshiba 3501XA CDROM drive. The installation works just fine, but when I try to reboot the system, I get the message Missing Operating System. .... ==== == Como Acompanhar uma Pergunta Algumas vezes você vai querer mandar informação adicional para uma questão que você já enviou. A melhor maneira de fazer isso é responder a sua própria mensagem original. Isto tem três vantagens: . Você inclui o texto da mensagem original, assim as pessoas saberão do que você está falando. Não esqueça de retirar texto desnecessário. . O texto no campo do assunto permanece o mesmo (você lembrou de colocar o assunto, não foi?). Muitos aplicativos ordenarão as mensagens pelo assunto. Isto ajuda o agrupamento de mensagens. . Os números de referência da mensagem no cabeçalho se referem à mensagem anterior. Alguns mailers, como o http://www.mutt.org/[mutt], podem agrupar as mensagens em __thread__, mostrando as relações exatas entre as mensagens. == Como Responder uma Pergunta Antes de responder uma pergunta na FreeBSD-questions, considere: . Muitas das diretivas usadas quando se está para escrever uma questão também são válidas para respondê-las. Leia-as. . Alguém já respondeu à pergunta? A maneira mais fácil de conferir isto é ordenando as mensagens recebidas pelo assunto: então (esperançosamente) você verá a pergunta seguida pelas respectivas respostas, todas juntas. + Se alguém já respondeu, isso não significa automaticamente que você não deve enviar outra resposta. Mas faz sentido ler todas as outras respostas primeiro. . Você tem algo para contribuir além do que já foi dito? Em geral, as respostas do tipo "Sim, eu também" não ajudam muito, embora haja exceções, como quando alguém está descrevendo um problema que está tendo, e não sabe se é culpa dela ou se existe algo de errado com o hardware ou software. Se você for enviar uma resposta do tipo "eu também", você também deverá incluir outras informações relevantes. . Tem certeza de que entendeu a pergunta? Muito freqüentemente, a pessoa que faz a pergunta é confusa ou não se expressa muito bem. Mesmo com o melhor entendimento do sistema, é fácil enviar uma resposta que não responde à pergunta. Isso não ajuda: você deixará a pessoa que enviou a pergunta ainda mais frustrada ou confusa do que nunca. Se ninguém mais responder e você também não tiver certeza, você sempre poderá pedir mais informações. . Tem certeza de que sua resposta está correta? Se não, espere um dia ou mais. Se ninguém mais aparecer com uma resposta melhor, você ainda pode responder e dizer, por exemplo, "Eu não sei se isso está correto, mas como ninguém mais respondeu, por que você não tenta substituir seu CDROM ATAPI com por sapo?". . A menos que haja uma boa razão para fazer o contrário, responda ao remetente e para a FreeBSD-questions. Muitas pessoas na FreeBSD-questions são "lurkers": elas aprendem lendo mensagens enviadas e respondidas por outras pessoas. Se você tirar uma mensagem que é de interesse geral da lista, você está privando essas pessoas de suas informações. Tenha cuidado com as respostas para grupo; Muitas pessoas enviam mensagens com centenas de CCs. Se este for o caso, certifique-se de reduzir as linhas Cc: apropriadamente. . Incluir texto relevante da mensagem original. Reduza ao mínimo, mas não exagere. O conteúdo original remanescente ainda deve possibilitar à alguém que não leu a mensagem original entender do que você está falando. . Use alguma técnica para identificar qual texto veio da mensagem original e qual texto você adicionou. Eu pessoalmente acho que a adição do "`>`" no inicio da mensagem original funciona bem. Deixando espaço em branco após o "`>`" e deixar linhas vazias entre o seu texto e o texto original, ambos tornam o resultado mais legível. . Coloque sua resposta no lugar correto (após o texto ao qual ela se refere). É muito difícil ler um encadeamento de respostas em que cada resposta vem antes do texto ao qual ela se refere. . A maioria dos programas de email mudam a linha do assunto em um resposta , adicionando no início desta um texto do tipo "Re:". Se seu programa não faz isso automaticamente, você deve fazer manualmente. . Se o remetente não respeitar as convenções de formato (linhas muito longas, linha de assunto imprópria), _por favor_ conserte-o. No caso de uma linha de assunto incorreta (como " HELP !! ?? "), mude a linha de assunto para (digamos) "Re: Dificuldades com a sincronização PPP (era: HELP !! ??)". Dessa forma, outras pessoas que tentam seguir o tópico terão menos dificuldade em segui-lo. + Nesses casos, é apropriado falar o que você fez e porque o fez, mas tente fazê-lo de forma a não ser rude. Se você notar que não consegue responder de uma forma que não seja rude, não responda. + Se você quer responder a uma mensagem somente pelo seu formato inadequado, responda-a somente para quem a enviou, não à lista. Você pode simplesmente enviar esta mensagem em resposta, se quiser. diff --git a/documentation/content/pt-br/articles/freebsd-update-server/_index.adoc b/documentation/content/pt-br/articles/freebsd-update-server/_index.adoc index c55d28bbcf..4125342c97 100644 --- a/documentation/content/pt-br/articles/freebsd-update-server/_index.adoc +++ b/documentation/content/pt-br/articles/freebsd-update-server/_index.adoc @@ -1,590 +1,600 @@ --- title: Construa seu próprio servidor de atualização do FreeBSD authors: - author: Jason Helfman email: jgh@FreeBSD.org copyright: 2009-2011, 2013 Jason Helfman releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "amd", "intel", "general"] --- = Construa seu próprio servidor de atualização do FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este artigo descreve a construção de um servidor de atualizações do FreeBSD interno. O https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] foi escrito por Colin Percival mailto:cperciva@FreeBSD.org[cperciva@FreeBSD.org], Oficial de Segurança Emérito do FreeBSD. Para usuários que acham conveniente atualizar seus sistemas em um servidor de atualização oficial, construir seu próprio FreeBSD Update Server pode ajudar a estender sua funcionalidade suportando versões do FreeBSD ajustadas manualmente ou fornecendo um espelho local que permitirá atualizações mais rápidas para várias máquinas. ''' toc::[] [[acknowledgments]] == Agradecimentos Este artigo foi publicado posteriormente no http://bsdmag.org/magazine/1021-bsd-as-a-desktop[BSD Magazine]. [[introduction]] == Introdução Usuários experientes ou administradores são muitas vezes responsáveis por várias máquinas ou ambientes. Eles entendem as difíceis demandas e desafios da manutenção de tal infraestrutura. A execução de um Servidor de Atualização do FreeBSD facilita a implantação de patches de segurança e software em máquinas de teste selecionadas antes de implementá-las nas maquinas em produção. Isso também significa que vários sistemas podem ser atualizados a partir da rede local, em vez de uma conexão de Internet potencialmente mais lenta. Este artigo descreve os passos envolvidos na criação de um Servidor de Atualização do FreeBSD interno. [[prerequisites]] == Pré-requisitos Para construir um Servidor de Atualização do FreeBSD interno, alguns requisitos devem ser atendidos. * Um sistema FreeBSD em execução. + [NOTE] ==== No mínimo, as atualizações requerem a criação de uma versão do FreeBSD maior ou igual a versão do release alvo para a distribuição. ==== * Uma conta de usuário com pelo menos 4 GB de espaço disponível. Isso permitirá a criação de atualizações para 7.1 e 7.2, mas os requisitos de espaço exatos podem mudar de versão para versão. * Uma conta com acesso ao man:ssh[1] em uma máquina remota para carregar atualizações distribuídas. * Um servidor web, como o link:{handbook}#network-apache[Apache], com mais da metade do espaço necessário para a construção. Por exemplo, as compilações de teste para 7.1 e 7.2 consomem uma quantidade total de 4 GB e o espaço do servidor da web necessário para distribuir essas atualizações é de 2.6 GB. * Conhecimento básico de shell script com o Bourne shell, man:sh[1]. [[Configuration]] == Configuração: Instalação & Configuração Faça o download do software https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] instalando package:devel/subversion[] e package:security/ca_root_nss[], e execute: [source,shell] .... % svn co https://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server .... Atualize o [.filename]#scripts/build.conf# apropriadamente. Ele é criado durante todas as operações de construção. Aqui está o [.filename]#build.conf# padrão, que deve ser modificado para se adequar ao seu ambiente. [.programlisting] .... # Main configuration file for FreeBSD Update builds. The # release-specific configuration data is lower down in # the scripts tree. # Location from which to fetch releases export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases <.> # Host platform export HOSTPLATFORM=`uname -m` # Host name to use inside jails export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net <.> # Location of SSH key export SSHKEY=/root/.ssh/id_dsa <.> # SSH account into which files are uploaded MASTERACCT=builder@wadham.daemonology.net <.> # Directory into which files are uploaded MASTERDIR=update-master.freebsd.org <.> .... Parâmetros para consideração seriam: <.> Este é o local onde as imagens ISO são baixadas (pela sub-rotina `fetchiso()` do [.filename]#scripts/build.subr#). A localização configurada não está limitada a URIs de FTP. Qualquer esquema de URI suportado pelo utilitário padrão man:fetch[] deve funcionar bem. Personalizações para o código de `fetchiso()` podem ser instaladas copiando o script padrão [.filename]#build.subr# para a área específica do release e da arquitetura em [.filename]#scripts/RELEASE/ARCHITECTURE/build.subr# e aplicando alterações locais. <.> O nome do host em construção. Esta informação será exibida em sistemas atualizados ao executar: + [source,shell] .... % uname -v .... + <.> A chave SSH para fazer upload de arquivos para o servidor de atualizações. Um par de chaves pode ser criado digitando `ssh-keygen -t dsa`. Este parâmetro é opcional; a autenticação de senha padrão será usada como um método de autenticação secundário quando a `SSHKEY` não estiver definida. A página de manual do man:ssh-keygen[1] contém informações mais detalhadas sobre o SSH e as etapas apropriadas para criar e usar um. <.> Conta para fazer upload de arquivos para o servidor de atualização. <.> Diretório no servidor de atualização para o qual os arquivos são enviados. O arquivo padrão [.filename]#build.conf# fornecido com o código-fonte do freebsd-update-server é adequado para a criação de versões i386 do FreeBSD. Como um exemplo de criação de um servidor de atualização para outras arquiteturas, as etapas a seguir descrevem as alterações necessárias na configuração para o amd64: [.procedure] . Crie um ambiente de compilação para o amd64: + [source,shell] .... % mkdir -p /usr/local/freebsd-update-server/scripts/7.2-RELEASE/amd64 .... . Instale um [.filename]#build.conf# no diretório de criação recém-criado. As opções de configuração de compilação para o FreeBSD 7.2-RELEASE com arquitetura amd64 devem ser semelhantes a: + [.programlisting] .... # SHA256 hash of RELEASE disc1.iso image. export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5 <.> # Components of the world, source, and kernels export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32" export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5 \ lib libexec release rescue sbin secure share sys tools \ ubin usbin cddl" export KERNELPARTS="generic" # EOL date export EOL=1275289200 <.> .... + <.> A chave man:sha256[1] usada para fazer o hash para a release desejada é publicada no respectivo https://www.FreeBSD.org/releases/[anúncio de release]. <.> Para gerar o número "End of Life" para o [.filename]#build.conf#, consulte o "EOL estimado" publicado no https://www.FreeBSD.org/security/[Site de Segurança do FreeBSD]. O valor de `EOL` pode ser derivado da data listada no site, usando o utilitário man:date[1], por exemplo: + [source,shell] .... % date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s' .... [[build]] == Compilando o Código de Atualização O primeiro passo é executar o [.filename]#scripts/make.sh#. Isso criará alguns binários, criará diretórios e irá gerar uma chave de assinatura RSA usada para aprovar as compilações. Nesta etapa, uma senha terá que ser fornecida para a criação final da chave de assinatura. [source,shell] .... # sh scripts/make.sh cc -O2 -fno-strict-aliasing -pipe findstamps.c -o findstamps findstamps.c: In function 'usage': findstamps.c:45: warning: incompatible implicit declaration of built-in function 'exit' cc -O2 -fno-strict-aliasing -pipe unstamp.c -o unstamp install findstamps ../bin install unstamp ../bin rm -f findstamps unstamp Generating RSA private key, 4096 bit long modulus ................................................................................++ ...................++ e is 65537 (0x10001) Public key fingerprint: 27ef53e48dc869eea6c3136091cc6ab8589f967559824779e855d58a2294de9e Encrypting signing key for root enter aes-256-cbc encryption password: Verifying - enter aes-256-cbc encryption password: .... [NOTE] ==== Mantenha um backup do fingerprint gerado. Este valor é necessário para o arquivo [.filename]#/etc/freebsd-update.conf# para as atualizações binárias. ==== Neste ponto, estamos prontos para montar uma construção. [source,shell] .... # cd /usr/local/freebsd-update-server # sh scripts/init.sh amd64 7.2-RELEASE .... O que se segue é uma amostra de uma execução da compilação __inicial__. [source,shell] .... # sh scripts/init.sh amd64 7.2-RELEASE Mon Aug 24 16:04:36 PDT 2009 Starting fetch for FreeBSD/amd64 7.2-RELEASE /usr/local/freebsd-update-server/work/7.2-RELE100 of 588 MB 359 kBps 00m00s Mon Aug 24 16:32:38 PDT 2009 Verifying disc1 hash for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 16:32:44 PDT 2009 Extracting components for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 16:34:05 PDT 2009 Constructing world+src image for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 16:35:57 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 23:36:24 UTC 2009 Building world for FreeBSD/amd64 7.2-RELEASE Tue Aug 25 00:31:29 UTC 2009 Distributing world for FreeBSD/amd64 7.2-RELEASE Tue Aug 25 00:32:36 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE Tue Aug 25 00:44:44 UTC 2009 Constructing world components for FreeBSD/amd64 7.2-RELEASE Tue Aug 25 00:44:56 UTC 2009 Distributing source for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 17:46:18 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 17:46:33 PDT 2009 Identifying extra documentation for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 17:47:13 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 17:47:18 PDT 2009 Indexing release for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 17:50:44 PDT 2009 Indexing world0 for FreeBSD/amd64 7.2-RELEASE Files built but not released: Files released but not built: Files which differ by more than contents: Files which differ between release and build: kernel|generic|/GENERIC/hptrr.ko kernel|generic|/GENERIC/kernel src|sys|/sys/conf/newvers.sh world|base|/boot/loader world|base|/boot/pxeboot world|base|/etc/mail/freebsd.cf world|base|/etc/mail/freebsd.submit.cf world|base|/etc/mail/sendmail.cf world|base|/etc/mail/submit.cf world|base|/lib/libcrypto.so.5 world|base|/usr/bin/ntpq world|base|/usr/lib/libalias.a world|base|/usr/lib/libalias_cuseeme.a world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a ... .... Então a compilação do world é executada novamente, com patches para world. Uma explicação mais detalhada pode ser encontrada em [.filename]#scripts/build.subr#. [WARNING] ==== Durante este segundo ciclo de compilação, o daemon do protocolo de tempo de rede, man:ntpd[8], é desativado. Segundo o Colin Percival mailto:cperciva@FreeBSD.org[cperciva@FreeBSD.org], Oficial de segurança emérito do FreeBSD, "a compilação do código do https://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/[freebsd-update-server] precisa identificar os timestamps que são armazenados nos arquivos para que possam ser ignorados ao comparar builds para determinar quais arquivos precisam ser atualizados. Essa busca de timestamp trabalha com duas construções com 400 dias de diferença e compara os resultados." ==== [source,shell] .... Mon Aug 24 17:54:07 PDT 2009 Extracting world+src for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 00:54:34 UTC 2010 Building world for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 01:49:42 UTC 2010 Distributing world for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 01:50:50 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 02:02:56 UTC 2010 Constructing world components for FreeBSD/amd64 7.2-RELEASE Wed Sep 29 02:03:08 UTC 2010 Distributing source for FreeBSD/amd64 7.2-RELEASE Tue Sep 28 19:04:31 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:04:46 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:04:51 PDT 2009 Indexing world1 for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:08:04 PDT 2009 Locating build stamps for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:10:19 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:10:19 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 19:10:20 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 12:16:57 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.2-RELEASE Mon Aug 24 12:16:59 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.2-RELEASE Files found which include build stamps: kernel|generic|/GENERIC/hptrr.ko kernel|generic|/GENERIC/kernel world|base|/boot/loader world|base|/boot/pxeboot world|base|/etc/mail/freebsd.cf world|base|/etc/mail/freebsd.submit.cf world|base|/etc/mail/sendmail.cf world|base|/etc/mail/submit.cf world|base|/lib/libcrypto.so.5 world|base|/usr/bin/ntpq world|base|/usr/include/osreldate.h world|base|/usr/lib/libalias.a world|base|/usr/lib/libalias_cuseeme.a world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a ... .... Finalmente, a construção é concluída. [source,shell] .... Values of build stamps, excluding library archive headers: v1.2 (Aug 25 2009 00:40:36) v1.2 (Aug 25 2009 00:38:22) @()FreeBSD 7.2-RELEASE 0: Tue Aug 25 00:38:29 UTC 2009 FreeBSD 7.2-RELEASE 0: Tue Aug 25 00:38:29 UTC 2009 root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC 7.2-RELEASE Mon Aug 24 23:55:25 UTC 2009 Mon Aug 24 23:55:25 UTC 2009 built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009 built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009 built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009 built by root@server.myhost.com on Tue Aug 25 00:16:15 UTC 2009 Mon Aug 24 23:46:47 UTC 2009 ntpq 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1) * Copyright (c) 1992-2009 The FreeBSD Project. Mon Aug 24 23:46:47 UTC 2009 Mon Aug 24 23:55:40 UTC 2009 Aug 25 2009 ntpd 4.2.4p5-a Mon Aug 24 23:55:52 UTC 2009 (1) ntpdate 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1) ntpdc 4.2.4p5-a Mon Aug 24 23:55:53 UTC 2009 (1) Tue Aug 25 00:21:21 UTC 2009 Tue Aug 25 00:21:21 UTC 2009 Tue Aug 25 00:21:21 UTC 2009 Mon Aug 24 23:46:47 UTC 2009 FreeBSD/amd64 7.2-RELEASE initialization build complete. Please review the list of build stamps printed above to confirm that they look sensible, then run sh -e approve.sh amd64 7.2-RELEASE to sign the release. .... Aprove a compilação se tudo estiver correto. Mais informações sobre como determinar isso podem ser encontradas no arquivo fonte distribuído chamado [.filename]#USAGE#. Execute [.filename]#scripts/approve.sh#, conforme indicado. Isso assinará a release e moverá os componentes para uma área de preparação adequada para o upload. [source,shell] .... # cd /usr/local/freebsd-update-server # sh scripts/mountkey.sh .... [source,shell] .... # sh -e scripts/approve.sh amd64 7.2-RELEASE Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.2-RELEASE Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.2-RELEASE Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.2-RELEASE Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.2-RELEASE Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE .... Após o processo de aprovação ser concluído, o procedimento de upload pode ser iniciado. [source,shell] .... # cd /usr/local/freebsd-update-server # sh scripts/upload.sh amd64 7.2-RELEASE .... [NOTE] ==== No caso de o código de atualização precisar ser reenviado, isso pode ser feito mudando para o diretório de distribuições públicas para o release alvo e atualizando os atributos do arquivo __carregado__. [source,shell] .... # cd /usr/local/freebsd-update-server/pub/7.2-RELEASE/amd64 # touch -t 200801010101.01 uploaded .... ==== Os arquivos enviados precisarão estar no diretório de documentos raiz do servidor web para que as atualizações sejam distribuídas. A configuração exata irá variar dependendo do servidor web usado. Para o servidor web Apache, consulte a sessão link:{handbook}#network-apache[Configuração de servidores Apache] no Handbook. Atualize o `KeyPrint` e `ServerName` do cliente no arquivo [.filename]#/etc/freebsd-update.conf#, e execute as atualizações conforme instruído na link:{handbook}#updating-upgrading-freebsdupdate[Seção de Atualização do FreeBSD] no Handbook. [IMPORTANT] ==== Para que o Servidor de Atualização do FreeBSD funcione corretamente, atualizações para ambas releases _atual_ e a release _que se deseja atualizar_ precisam ser compilados. Isso é necessário para determinar as diferenças de arquivos entre as releases. Por exemplo, ao atualizar um sistema FreeBSD de 7.1-RELEASE para 7.2-RELEASE, as atualizações precisarão ser construídas e carregadas em seu servidor de distribuição para ambas as versões. ==== Para referência, toda a execução do link:../../../source/articles/freebsd-update-server/init.txt[init.sh] é anexada. [[patch]] == Compilando um Patch Toda vez que é anunciado um https://www.FreeBSD.org/security/advisories/[aviso de segurança] ou uma https://www.FreeBSD.org/security/notices/[notificação de segurança], um patch de atualização pode ser construído. Para este exemplo, o 7.1-RELEASE será usado. Algumas suposições são feitas para uma versão diferente: * Configure a estrutura de diretórios correta para a compilação inicial. * Execute uma compilação inicial para o 7.1-RELEASE. Crie o diretório de correção do respectivo release no diretório [.filename]#/usr/local/freebsd-update-server/patches/#. [source,shell] .... % mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/ % cd /usr/local/freebsd-update-server/patches/7.1-RELEASE .... Como exemplo, pegue o patch para man:named[8]. Leia o comunicado, e pegue o arquivo necessário de https://www.FreeBSD.org/security/advisories/[Avisos de Segurança do FreeBSD]. Mais informações sobre a interpretação do comunicado podem ser encontradas no link:{handbook}#security-advisories[Handbook do FreeBSD]. No https://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc[resumo de segurança], este comunicado é chamado `SA-09:12.bind`. Depois de baixar o arquivo, é necessário renomear o arquivo para um nível de correção apropriado. Sugere-se manter isso consistente com os níveis oficiais de correção do FreeBSD, mas seu nome pode ser escolhido livremente. Para esta compilação, vamos seguir a prática atualmente estabelecida do FreeBSD e chamar isso de `p7`. Renomeie o arquivo: [source,shell] .... % cd /usr/local/freebsd-update-server/patches/7.1-RELEASE/; mv bind.patch 7-SA-09:12.bind .... [NOTE] ==== Ao executar uma compilação em nível de patch, supõe-se que os patches anteriores estejam no lugar. Quando uma compilação de patch é executada, ela executará todas os patches contidos no diretório de patch. Pode haver patches personalizados adicionados a qualquer compilação. Use o número zero ou qualquer outro número. ==== [WARNING] ==== Cabe ao administrador do Servidor de Atualização do FreeBSD tomar as medidas apropriadas para verificar a autenticidade de cada patch. ==== Neste ponto, um _diff_ está pronto para ser construído. O software verifica primeiro para ver se um [.filename]#scripts/init.sh# foi executado na respectiva versão antes de executar a construção do diff. [source,shell] .... # cd /usr/local/freebsd-update-server # sh scripts/diff.sh amd64 7.1-RELEASE 7 .... O que se segue é um exemplo de uma execução de uma compilação __diferencial__. [source,shell] .... # sh -e scripts/diff.sh amd64 7.1-RELEASE 7 Wed Aug 26 10:09:59 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 17:10:25 UTC 2009 Building world for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 18:05:11 UTC 2009 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 18:06:16 UTC 2009 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 18:17:50 UTC 2009 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 18:18:02 UTC 2009 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 11:19:23 PDT 2009 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 11:19:37 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 11:19:42 PDT 2009 Indexing world0 for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 11:23:02 PDT 2009 Extracting world+src for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 18:23:29 UTC 2010 Building world for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 19:18:15 UTC 2010 Distributing world for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 19:19:18 UTC 2010 Building and distributing kernels for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 19:30:52 UTC 2010 Constructing world components for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 19:31:03 UTC 2010 Distributing source for FreeBSD/amd64 7.1-RELEASE-p7 Thu Sep 30 12:32:25 PDT 2010 Moving components into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:32:39 PDT 2009 Extracting extra docs for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:32:43 PDT 2009 Indexing world1 for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:35:54 PDT 2009 Locating build stamps for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:36:58 PDT 2009 Reverting changes due to build stamps for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:37:14 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:37:14 PDT 2009 Preparing to copy files into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:37:15 PDT 2009 Copying data files into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:43:23 PDT 2009 Copying metadata files into staging area for FreeBSD/amd64 7.1-RELEASE-p7 Wed Aug 26 12:43:25 PDT 2009 Constructing metadata index and tag for FreeBSD/amd64 7.1-RELEASE-p7 ... Files found which include build stamps: kernel|generic|/GENERIC/hptrr.ko kernel|generic|/GENERIC/kernel world|base|/boot/loader world|base|/boot/pxeboot world|base|/etc/mail/freebsd.cf world|base|/etc/mail/freebsd.submit.cf world|base|/etc/mail/sendmail.cf world|base|/etc/mail/submit.cf world|base|/lib/libcrypto.so.5 world|base|/usr/bin/ntpq world|base|/usr/include/osreldate.h world|base|/usr/lib/libalias.a world|base|/usr/lib/libalias_cuseeme.a world|base|/usr/lib/libalias_dummy.a world|base|/usr/lib/libalias_ftp.a ... Values of build stamps, excluding library archive headers: v1.2 (Aug 26 2009 18:13:46) v1.2 (Aug 26 2009 18:11:44) @()FreeBSD 7.1-RELEASE-p7 0: Wed Aug 26 18:11:50 UTC 2009 FreeBSD 7.1-RELEASE-p7 0: Wed Aug 26 18:11:50 UTC 2009 root@server.myhost.com:/usr/obj/usr/src/sys/GENERIC 7.1-RELEASE-p7 Wed Aug 26 17:29:15 UTC 2009 Wed Aug 26 17:29:15 UTC 2009 built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009 built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009 built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009 built by root@server.myhost.com on Wed Aug 26 17:49:58 UTC 2009 Wed Aug 26 17:20:39 UTC 2009 ntpq 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1) * Copyright (c) 1992-2009 The FreeBSD Project. Wed Aug 26 17:20:39 UTC 2009 Wed Aug 26 17:29:30 UTC 2009 Aug 26 2009 ntpd 4.2.4p5-a Wed Aug 26 17:29:41 UTC 2009 (1) ntpdate 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1) ntpdc 4.2.4p5-a Wed Aug 26 17:29:42 UTC 2009 (1) Wed Aug 26 17:55:02 UTC 2009 Wed Aug 26 17:55:02 UTC 2009 Wed Aug 26 17:55:02 UTC 2009 Wed Aug 26 17:20:39 UTC 2009 ... .... As atualizações são impressas e a aprovação é solicitada. [source,shell] .... New updates: kernel|generic|/GENERIC/kernel.symbols|f|0|0|0555|0|7c8dc176763f96ced0a57fc04e7c1b8d793f27e006dd13e0b499e1474ac47e10| kernel|generic|/GENERIC/kernel|f|0|0|0555|0|33197e8cf15bbbac263d17f39c153c9d489348c2c534f7ca1120a1183dec67b1| kernel|generic|/|d|0|0|0755|0|| src|base|/|d|0|0|0755|0|| src|bin|/|d|0|0|0755|0|| src|cddl|/|d|0|0|0755|0|| src|contrib|/contrib/bind9/bin/named/update.c|f|0|10000|0644|0|4d434abf0983df9bc47435670d307fa882ef4b348ed8ca90928d250f42ea0757| src|contrib|/contrib/bind9/lib/dns/openssldsa_link.c|f|0|10000|0644|0|c6805c39f3da2a06dd3f163f26c314a4692d4cd9a2d929c0acc88d736324f550| src|contrib|/contrib/bind9/lib/dns/opensslrsa_link.c|f|0|10000|0644|0|fa0f7417ee9da42cc8d0fd96ad24e7a34125e05b5ae075bd6e3238f1c022a712| ... FreeBSD/amd64 7.1-RELEASE update build complete. Please review the list of build stamps printed above and the list of updated files to confirm that they look sensible, then run sh -e approve.sh amd64 7.1-RELEASE to sign the build. .... Siga o mesmo processo descrito anteriormente para aprovar uma compilação: [source,shell] .... # sh -e scripts/approve.sh amd64 7.1-RELEASE Wed Aug 26 12:50:06 PDT 2009 Signing build for FreeBSD/amd64 7.1-RELEASE Wed Aug 26 12:50:06 PDT 2009 Copying files to patch source directories for FreeBSD/amd64 7.1-RELEASE Wed Aug 26 12:50:06 PDT 2009 Copying files to upload staging area for FreeBSD/amd64 7.1-RELEASE Wed Aug 26 12:50:07 PDT 2009 Updating databases for FreeBSD/amd64 7.1-RELEASE Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.1-RELEASE The FreeBSD/amd64 7.1-RELEASE update build has been signed and is ready to be uploaded. Remember to run sh -e umountkey.sh to unmount the decrypted key once you have finished signing all the new builds. .... Depois de aprovar a compilação, faça o upload do software: [source,shell] .... # cd /usr/local/freebsd-update-server # sh scripts/upload.sh amd64 7.1-RELEASE .... Para referência, toda a execução do link:../../../source/articles/freebsd-update-server/diff.txt[diff.sh] é anexada. [[tips]] == Dicas * Se uma versão personalizada for criada usando o procedimento `make release` link:{releng}#release-build[nativo], o `freebsd-update-server` funcionará a partir do seu release. Como exemplo, uma versão sem ports ou documentação pode ser construída limpando funcionalidades de limpeza pertinentes às sub-rotinas de documentação `findextradocs()`, `addextradocs()` e alterando o local de download em `fetchiso()`, respectivamente, em [.filename]#scripts/build.subr#. Como último passo, altere o hash man:sha256[1] no arquivo [.filename]#build.conf# sob sua respectiva versão e arquitetura e você estará pronto para criar sua versão personalizada. + [.programlisting] .... # Compare ${WORKDIR}/release and ${WORKDIR}/$1, identify which parts # of the world|doc subcomponent are missing from the latter, and # build a tarball out of them. findextradocs () { } # Add extra docs to ${WORKDIR}/$1 addextradocs () { } .... * Adicionando flags `-j _NUMERO_` para os alvos `buildworld` e `obj` no script [.filename]#scripts/build.subr# pode acelerar o processamento, dependendo do hardware usado, no entanto, não é necessário. O uso dessas flags em outros alvos não é recomendado, pois pode tornar a construção não confiável. + [.programlisting] .... # Build the world log "Building world" cd /usr/src && make -j 2 ${COMPATFLAGS} buildworld 2>&1 # Distribute the world log "Distributing world" cd /usr/src/release && make -j 2 obj && make ${COMPATFLAGS} release.1 release.2 2>&1 .... * Crie um registro link:{handbook}#network-dns[DNS] apropriado para o servidor de atualizações e coloque outros por trás dele com variáveis de pesos diferentes. O uso desse recurso fornecerá espelhos de atualização, no entanto, essa dica não é necessária, a menos que você deseje fornecer um serviço redundante. + [.programlisting] .... _http._tcp.update.myserver.com. IN SRV 0 2 80 host1.myserver.com. IN SRV 0 1 80 host2.myserver.com. IN SRV 0 0 80 host3.myserver.com. .... diff --git a/documentation/content/pt-br/articles/geom-class/_index.adoc b/documentation/content/pt-br/articles/geom-class/_index.adoc index 9fa8df9926..ab9559ae01 100644 --- a/documentation/content/pt-br/articles/geom-class/_index.adoc +++ b/documentation/content/pt-br/articles/geom-class/_index.adoc @@ -1,348 +1,358 @@ --- title: Escrevendo uma classe GEOM authors: - author: Ivan Voras email: ivoras@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "intel", "general"] --- = Escrevendo uma classe GEOM :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este texto documenta alguns pontos de partida no desenvolvimento de classes GEOM e módulos do kernel em geral. Supõe-se que o leitor esteja familiarizado com a programação C do userland. ''' toc::[] [[intro]] == Introdução [[intro-docs]] === Documentação A documentação sobre programação do kernel é escassa - é uma das poucas áreas na qual não há quase nada de tutoriais amigáveis, e a frase "usa a fonte!" realmente é verdadeira. No entanto, existem alguns pedaços (alguns deles seriamente desatualizados) flutuando por ai e que devem ser estudados antes de começar a codificar: * O link:{developers-handbook}[Manual do Desenvolvedor do FreeBSD] - parte do projeto de documentação, ele não contém nenhum informação específica para a programação do kernel, mas possui algumas informações gerais úteis. * O link:{arch-handbook}[Manual de Arquitetura do FreeBSD] - também do projeto de documentação, contém descrições de várias instalações e procedimentos de baixo nível. O capítulo mais importante é o 13, link:{arch-handbook}#driverbasics[Escrevendo drivers de dispositivo FreeBSD]. * A seção Blueprints do site do http://www.freebsddiary.org[FreeBSD Diary] contém vários artigos interessantes sobre os recursos do kernel. * As páginas de manual na seção 9 - para documentação importante sobre as funções do kernel. * A página man man:geom[4] e os http://phk.freebsd.dk/pubs/[Slides sobre o GEOM de PHK] - para uma introdução geral do subsistema GEOM. * Páginas de manual man:g_bio[9], man:g_event[9], man:g_data[9], man:g_geom[9], man:g_provider[9] man:g_consumer[9], man:g_access[9] & outros ligados a partir deles, para documentação sobre funcionalidades específicas. * A página do manual man:style[9] - para documentação sobre as convenções de estilo de codificação que devem ser seguidas para qualquer código que se destine a ser incorporado à Árvore do Subversion do FreeBSD. [[prelim]] == Preliminares A melhor maneira de fazer o desenvolvimento do kernel é ter (pelo menos) dois computadores separados. Um deles conteria o ambiente de desenvolvimento e o código fonte, e o outro seria usado para testar o código recém escrito, inicializando por meio da rede e montando seu sistema de arquivo a partir do primeiro computador. Desta forma, se o novo código contiver erros e travar a máquina, isso não irá atrapalhar o código fonte (e nem nenhum outros dado "vivo"). O segundo sistema nem sequer requer um monitor adequado. Em vez disso, ele pode ser conectado por meio de um cabo serial ou KVM ao primeiro computador. Mas, como nem todo mundo tem dois ou mais computadores à mão, há algumas coisas que podem ser feitas para preparar um sistema "vivo " para desenvolver código para o kernel. Esta configuração também é aplicável para desenvolvimento em uma máquina virtual criada com o http://www.vmware.com/[VMWare] ou com o http://www.qemu.org/[QEmu] (a próxima melhor coisa depois de uma máquina de desenvolvimento dedicada). [[prelim-system]] === Modificando um sistema para desenvolvimento Para qualquer programação do kernel, um kernel com a opção `INVARIANTS` ativada é obrigatório. Então, digite estas linhas no seu arquivo de configuração do kernel: [.programlisting] .... options INVARIANT_SUPPORT options INVARIANTS .... Para ter um maior nível de depuração, você também devrá incluir o suporte ao WITNESS, o qual irá alertá-lo sobre erros relacionados a bloqueios (locking): [.programlisting] .... options WITNESS_SUPPORT options WITNESS .... Para depurar despejos de memória, é necessário um kernel com símbolos de depuração: [.programlisting] .... makeoptions DEBUG=-g .... Com a maneira usual de instalar o kernel (`make installkernel`) o kernel de depuração não será instalado automaticamente. Ele é chamado de [.filename]#kernel.debug# e fica localizado em [.filename]#/usr/obj/usr/src/sys/KERNELNAME/#. Por conveniência, deve ser copiado para [.filename]#/boot/kernel/#. Outra conveniência é habilitar o depurador do kernel para que você possa examinar o panic do kernel quando isso acontece. Para isso, insira as seguintes linhas no seu arquivo de configuração do kernel: [.programlisting] .... options KDB options DDB options KDB_TRACE .... Para que isso funcione, você pode precisar definir um sysctl (se ele não estiver ativado por padrão): [.programlisting] .... debug.debugger_on_panic=1 .... Kernel panics acontecerão, portanto, deve-se ter cuidado com o cache do sistema de arquivos. Em particular, ter o softupdates habilitado pode significar que a versão mais recente do arquivo pode ser perdida se um panic ocorrer antes de ser committed para armazenamento. Desativar o softupdates produz um grande impacto na performance e ainda não garante a consistência dos dados. A montagem do sistema de arquivos com a opção "sync" é necessária para isso. Para um compromisso, os atrasos do cache de softupdates podem ser encurtados. Existem três sysctl's que são úteis para isso (melhor ser configurado em [.filename]#/etc/sysctl.conf#): [.programlisting] .... kern.filedelay=5 kern.dirdelay=4 kern.metadelay=3 .... Os números representam segundos. Para depurar os panics do kernel, os dumps do núcleo do kernel são necessários. Como um kernel panic pode tornar os sistemas de arquivos inutilizáveis, esse despejo de memória é primeiramente gravado em uma partição bruta. Normalmente, esta é a partição de swap. Essa partição deve ser pelo menos tão grande quanto a RAM física na máquina. Na próxima inicialização, o despejo é copiado para um arquivo normal. Isso acontece depois que os sistemas de arquivos são verificados e montados e antes que o swap seja ativado. Isto é controlado com duas variáveis [.filename]#/etc/rc.conf#: [.programlisting] .... dumpdev="/dev/ad0s4b" dumpdir="/usr/core .... A variável `dumpdev` especifica a partição de swap e `dumpdir` informa ao sistema onde no sistema de arquivos ele deverá realocar o dump principal na reinicialização. A gravação de core dumps é lenta e leva muito tempo, então se você tiver muita memória (>256M) e muitos panics, pode ser frustrante sentar e esperar enquanto isso é feito (duas vezes - primeiro para gravar para o swap, depois para realocá-lo para o sistema de arquivos). É conveniente limitar a quantidade de RAM que o sistema usará através de uma variável do [.filename]#/boot/loader.conf#: [.programlisting] .... hw.physmem="256M" .... Se os panics são frequentes e os sistemas de arquivos são grandes (ou você simplesmente não confia em softupdates + background fsck), é aconselhável desligar o fsck em background através da variável [.filename]#/etc/rc.conf#: [.programlisting] .... background_fsck="NO" .... Dessa forma, os sistemas de arquivos sempre serão verificados quando necessário. Observe que, com o fsck em segundo plano, um novo panic pode acontecer enquanto ele está verificando os discos. Novamente, a maneira mais segura é não ter muitos sistemas de arquivos locais, usando o outro computador como um servidor NFS. [[prelim-starting]] === Começando o projeto Para o propósito de criar uma nova classe GEOM, um subdiretório vazio deve ser criado sob um diretório arbitrário acessível pelo usuário. Você não precisa criar o diretório do módulo em [.filename]#/usr/src#. [[prelim-makefile]] === O Makefile É uma boa prática criar [.filename]#Makefiles# para cada projeto de codificação não trivial, o que obviamente inclui módulos do kernel. Criar o [.filename]#Makefile# é simples graças a um extenso conjunto de rotinas auxiliares fornecidas pelo sistema. Em suma, aqui está um exemplo de como um Makefile [.filename]#mínimo# para um módulo do kernel se parece: [.programlisting] .... SRCS=g_journal.c KMOD=geom_journal .include .... Este [.filename]#Makefile# (com nomes de arquivos alterados) serve para qualquer módulo do kernel, e uma classe GEOM pode residir em apenas um módulo do kernel. Se mais de um arquivo for necessário, liste-o na variável `SRCS`, separado com espaço em branco de outros nomes de arquivos. [[kernelprog]] == Programação do kernel do FreeBSD [[kernelprog-memalloc]] === Alocação de memória Veja o man:malloc[9]. A alocação básica de memória é apenas ligeiramente diferente do seu userland equivalente. Mais notavelmente, `malloc`() e `free`() aceitam parâmetros adicionais conforme descrito na página do manual. Um "malloc type" deve ser declarado na seção de declaração de um arquivo fonte, assim: [.programlisting] .... static MALLOC_DEFINE(M_GJOURNAL, "gjournal data", "GEOM_JOURNAL Data"); .... Para usar esta macro, os cabeçalhos [.filename]#sys/param.h#, [.filename]#sys/kernel.h# e [.filename]#sys/malloc.h# devem ser incluídos. Existe outro mecanismo para alocar memória, o UMA (Universal Memory Allocator). Veja man:uma[9] para detalhes, mas ele é um tipo especial de alocador usado principalmente para alocação rápida de listas compostas de itens do mesmo tamanho (por exemplo, matrizes dinâmicas de estruturas). [[kernelprog-lists]] === Listas e filas Veja man:queue[3]. Há MUITOS casos quando uma lista de coisas precisa ser mantida. Felizmente, essa estrutura de dados é implementada (de várias maneiras) por macros C incluídas no sistema. O tipo de lista mais usado é o TAILQ, porque é o mais flexível. É também aquele com os maiores requisitos de memória (seus elementos são duplamente vinculados) e também o mais lento (embora a variação de velocidade seja mais da ordem de várias instruções da CPU, portanto, ela não deve ser levada a sério). Se a velocidade de recuperação de dados for muito importante, veja man:tree[3] e man:hashinit[9]. [[kernelprog-bios]] === BIOS A estrutura `bio` é usada para todas e quaisquer operações de Input/Output relativas ao GEOM. Ele basicamente contém informações sobre qual dispositivo ('provedor') deve satisfazer a solicitação, tipo de pedido, offset, comprimento, ponteiro para um buffer e um monte de sinalizadores "específicos do usuário" e campos que podem ajudar a implementar vários hacks. O importante aqui é que os `bio`-s são tratados de forma assíncrona. Isso significa que, na maior parte do código, não há nenhum análogo as chamadas man:read[2] e man:write[2] que não retornam até que uma solicitação seja feita. Em vez disso, uma função fornecida pelo desenvolvedor é chamada como uma notificação quando a solicitação é concluída (ou resulta em erro). O modelo de programação assíncrona (também chamado de "orientado a eventos") é um pouco mais difícil do que o imperativo muito mais usado no userland (pelo menos leva um tempo para se acostumar com isso). Em alguns casos, as rotinas auxiliares `g_write_data`() e `g_read_data`() podem ser usadas, mas __nem sempre__. Em particular, elas não podem ser usadas quando um mutex é mantido; por exemplo, o mutex de topologia GEOM ou o mutex interno mantido durante as funções `.start`() e `.stop`(). [[geom]] == Programação GEOM [[geom-ggate]] === Ggate Se o desempenho máximo não for necessário, uma maneira muito mais simples de fazer uma transformação de dados é implementá-lo na área do usuário por meio do recurso ggate (GEOM gate). Infelizmente, não existe uma maneira fácil de converter ou até mesmo compartilhar código entre as duas abordagens. [[geom-class]] === Classe GEOM Classes GEOM são transformações nos dados. Essas transformações podem ser combinadas em uma forma de árvore. Instâncias de classes GEOM são chamadas de __geoms__. Cada classe GEOM possui vários "métodos de classe" que são chamados quando não há nenhuma instância geom disponível (ou simplesmente não estão vinculados a uma única instância): * `.init` é chamada quando o GEOM toma conhecimento de uma classe GEOM (quando o módulo do kernel é carregado). * `.fini` é chamada quando o GEOM abandona a classe (quando o módulo é descarregado) * `.taste` é chamada next, uma vez para cada provedor que o sistema tiver disponível. Se aplicável, essa função geralmente criará e iniciará uma instância geom. * `.destroy_geom` é chamada quando o geom deve ser desfeito * `.ctlconf` é chamado quando o usuário solicita a reconfiguração do geom existente Também são definidas as funções de evento GEOM, que serão copiadas para a instância geom. O campo `.geom` na estrutura `g_class` é uma LISTA de geoms instanciados a partir da classe. Estas funções são chamadas a partir da thread g_event do kernel. [[geom-softc]] === Softc O nome "softc" é um termo legado para "dados privados do driver". O nome provavelmente vem do termo arcaico "bloco de controle de software". No GEOM, ele é uma estrutura (mais precisamente: ponteiro para uma estrutura) que pode ser anexada a uma instância geom para armazenar quaisquer dados que sejam privados para a instância geom. A maioria das classes GEOM possui os seguintes membros: * `struct g_provider *provider` : O "provedor" que este geom instância * `uint16_t n_disks` : Número de consumidores que este geom consome * `struct g_consumer \**disks`: Array de `struct g_consumer*`. (Não é possível usar apenas uma única via indireta porque o struct g_consumer* é criado em nosso nome pela GEOM). A estrutura `softc` contém todo o estado da instância geom. Cada instância geom possui seu próprio softc. [[geom-metadata]] === Metadados O formato dos metadados é mais ou menos dependente da classe, mas DEVE começar com: * Buffer de 16 bytes para uma assinatura de terminação nula (geralmente o nome da classe) * ID da versão uint32 Assume-se que as classes geom sabem como lidar com metadados com ID de versão menores que os deles. Os metadados estão localizados no último setor do provedor (e, portanto, devem caber nele). (Tudo isso depende da implementação, mas todo o código existente funciona assim, e é suportado por bibliotecas.) [[geom-creating]] === Rotulando/criando um GEOM A sequência de eventos é: * o usuário chama o utilitário man:geom[8] (ou um de seus equivalentes hardlinked) * o utilitário descobre qual classe geom ele é suposto manipular e procura pela biblioteca [.filename]#geom_CLASSNAME.so# (geralmente em [.filename]#/lib/geom#). * ele man:dlopen[3]-s a biblioteca, extrai as definições dos parâmetros da linha de comandos e funções auxiliares. No caso da criação/rotulação de um novo geom, isso é o que acontece: * O man:geom[8] procura no argumento da linha de comando pelo comando (geralmente `label`) e chama uma função auxiliar . * A função auxiliar verifica parâmetros e reúne metadados, que são gravados em todos os provedores envolvidos. * Este "estraga" geoms existentes (se existirem) e inicializa uma nova rodada de "degustação" dos provedores. A classe geom pretendida reconhece os metadados e carrega o geom. (A sequência de eventos acima é dependente da implementação, mas todo o código existente funciona assim, e é suportado pelas bibliotecas.) [[geom-command]] === Estrutura do Comando GEOM A biblioteca helper [.filename]#geom_CLASSNAME.so# exporta a estrutura `class_commands`, que é uma matriz dos elementos `struct g_command`. Os comandos são uniformes no formato e se parecem com: [.programlisting] .... verb [-options] geomname [other] .... Verbos comuns são: * label - para gravar metadados em dispositivos para que eles possam ser reconhecidos em degustações e criados em geoms * destroy - para destruir metadados, para que as geoms sejam destruídas Opções comuns são: * `-v` : be verbose * `-f` : force Muitas ações, como rotular e destruir metadados, podem ser executadas no userland. Para isso, `struct g_command` fornece o campo `gc_func` que pode ser definido para uma função (no mesmo [.filename]#.so#) que será chamada para processar um verbo. Se `gc_func` for NULL, o comando será passado para o módulo do kernel, para a função `.ctlreq` da classe geom. [[geom-geoms]] === Geoms Geoms são instâncias de classes GEOM. Eles possuem dados internos (uma estrutura softc) e algumas funções com as quais eles respondem a eventos externos. As funções de evento são: * `.acess`: calcula permissões (leitura / escrita / exclusiva) * `.dumpconf`: retorna informações formatadas em XML sobre o geom * `.orphan`: chamado quando algum provedor subjacente é desconectado * `.spoiled`: chamado quando algum provedor subjacente é gravado * `.start`: lida com I/O Estas funções são chamadas a partir da thread `g_down` do kernel e não pode haver sleeping neste contexto, (veja a definição de sleeping em outro lugar) o que limita um pouco o que pode ser feito, mas força o manuseio a ser rápido . Destes, a função mais importante para fazer o trabalho útil real é a função `.start`(), que é chamada quando uma requisição BIO chega para um provedor gerenciado por uma instância da classe geom. [[geom-threads]] === Threads GEOM Existem três threads de kernel criados e executados pelo framework GEOM: * `g_down` : trata de solicitações provenientes de entidades de alto nível (como uma solicitação do userland) no caminho para dispositivos físicos * `g_up` : lida com respostas de drivers de dispositivos para solicitações feitas por entidades de nível superior * `g_event` : lida com todos os outros casos: criação de instâncias geom, contagem de acessos, eventos "spoil", etc. Quando um processo do usuário emite um pedido de "leitura de dados X no deslocamento Y de um arquivo", isto é o que acontece: * O sistema de arquivos converte o pedido em uma instância struct bio e o transmite para o subsistema GEOM. Ele sabe o que a instância geom deve manipular porque os sistemas de arquivos são hospedados diretamente em uma instância geom. * A requisição termina como uma chamada para a função `.start`() feita para a thread g_down e atinge a instância geom de nível superior. * Essa instância geom de nível superior (por exemplo, o segmentador de partições) determina que a solicitação deve ser roteada para uma instância de nível inferior (por exemplo, o driver de disco). Ele faz uma cópia da solicitação bio (solicitações bio _SEMPRE_ precisam ser copiadas entre instâncias, com `g_clone_bio`()!), modifica os campos de dados offset e de provedor de destino e executa a cópia com `g_io_request`() * O driver de disco obtém a solicitação bio também como uma chamada para `.start`() na thread `g_down`. Ela fala com o hardware, recupera os dados e chama `g_io_deliver`() na bio. * Agora, a notificação de bio conclusão "borbulha" na thread `g_up`. Primeiro, o slicer de partição obtém `.done`() chamado na thread `g_up`, ele usa as informações armazenadas na bio para liberar a estrutura `bio` clonada (com `g_destroy_bio`()) e chama `g_io_deliver`() no pedido original. * O sistema de arquivos obtém os dados e os transfere para o usuário. Veja a página de manual para o man:g_bio[9] para obter informações sobre como os dados são passados para frente e para trás na estrutura `bio` (observe em particular os campos `bio_parent` e `bio_children` e como eles são manipulados). Uma característica importante: __NAS THREADS G_UP E G_DOWN NÃO SE PODE DORMIR (SELEEPING)__. Isso significa que nenhuma das seguintes coisas pode ser feita nessas threads (a lista não é completa, mas apenas informativa): * Chamadas para `msleep`() e `tsleep`(), obviamente. * Chamadas para `g_write_data`() e `g_read_data`(), porque estes dormem entre passar os dados para os consumidores e retornar. * Esperando I/O. * Chamadas para man:malloc[9] e `uma_zalloc`() com o conjunto de flags `M_WAITOK` * sx e outros sleepable locks Esta restrição está aqui para impedir que o código GEOM obstrua o caminho da solicitação de I/O, já que sleeping normalmente não é limitado pelo tempo e não pode haver garantias sobre quanto tempo levará (também existem algumas outras razões mais técnicas). Isso também significa que não existe muito o que possa ser feito nessas threads; por exemplo, quase qualquer coisa complexa requer alocação de memória. Felizmente, existe uma saída: criar threads adicionais no kernel. [[geom-kernelthreads]] === Threads de kernel para uso no código GEOM As threads do kernel são criadas com a função man:kthread_create[9], e elas são semelhantes aos threads do userland no comportamento, eles somente não podem retornar ao chamador para exprimir a conclusão, mas deve chamar man:kthread_exit[9]. No código GEOM, o uso usual de threads é para descarregar o processamento de requisições da thread `g_down` (a função `.start`). Estas threads se parecem com um "event handlers": elas têm uma lista encadeada de eventos associados a elas (nos quais eventos podem ser postados por várias funções em várias threads, portanto, devem ser protegidos por um mutex), pegam os eventos da lista, um por um, e processa-os em uma grande instrução `switch`(). A principal vantagem de usar uma thread para lidar com solicitações de I/O é que ela pode dormir quando necessário. Agora, isso parece bom, mas deve ser cuidadosamente pensado. Dormir é bom e muito conveniente, mas pode ser muito efetivo em destruir o desempenho da transformação geom. As classes extremamente sensíveis ao desempenho provavelmente devem fazer todo o trabalho na chamada de função `.start`(), tomando muito cuidado para lidar com erros de falta de memória e similares. O outro benefício de ter uma thread de manipulação de eventos como essa é serializar todas as solicitações e respostas provenientes de diferentes threads geom em uma thread. Isso também é muito conveniente, mas pode ser lento. Na maioria dos casos, o tratamento de pedidos `.done`() pode ser deixado para a thread `g_up`. Mutexes no kernel do FreeBSD (veja man:mutex[9]) têm uma distinção de seus primos mais comuns do userland - o código não pode dormir enquanto estiver segurando um mutex). Se o código precisar dormir muito, os bloqueios man:sx[9] podem ser mais apropriados. Por outro lado, se você faz quase tudo em um único thread, você pode se safar sem utilizar mutexes. diff --git a/documentation/content/pt-br/articles/gjournal-desktop/_index.adoc b/documentation/content/pt-br/articles/gjournal-desktop/_index.adoc index 3e5fcec4b3..7e33b843ea 100644 --- a/documentation/content/pt-br/articles/gjournal-desktop/_index.adoc +++ b/documentation/content/pt-br/articles/gjournal-desktop/_index.adoc @@ -1,433 +1,443 @@ --- title: Implementando o UFS Journaling em um Desktop PC authors: - author: Manolis Kiagias email: manolis@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Implementando o UFS Journaling em um Desktop PC :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] ifeval::["{backend}" == "html5"] :imagesdir: ../../../images/articles/gjournal-desktop/ endif::[] ifeval::["{backend}" == "pdf"] :imagesdir: ../../../../static/images/articles/gjournal-desktop/ endif::[] ifeval::["{backend}" == "epub3"] :imagesdir: ../../../../static/images/articles/gjournal-desktop/ endif::[] [.abstract-title] Resumo Um sistema de arquivos com journaling usa um log para registrar todas as transações que ocorrem no sistema de arquivos e preserva sua integridade em caso de falha do sistema ou falta de energia. Embora ainda seja possível perder as alterações não salvas nos arquivos, o journaling elimina quase completamente a possibilidade de corrupção do sistema de arquivos causada por um desligamento abrupto. Ele também reduz ao mínimo o tempo necessário para a verificação do sistema de arquivos após a falha. Embora o sistema de arquivos UFS empregado pelo FreeBSD não implemente o journaling em si, a nova classe de journal do framework GEOM no FreeBSD 7._X_ pode ser usada para fornecer journaling independente do sistema de arquivos. Este artigo explica como implementar o UFS journaling em um cenário típico de PC de mesa. ''' toc::[] [[introduction]] == Introdução Embora os servidores profissionais estejam geralmente bem protegidos contra desligamentos imprevistos, um desktop típico fica à mercê de falhas de energia, reinicializações acidentais e outros incidentes relacionados ao usuário que podem levar a paradas abruptas. Os soft updates costumam proteger o sistema de arquivos de maneira eficiente nestes casos, embora na maioria das vezes seja necessária uma longa verificação em background. Em raras ocasiões, a corrupção do sistema de arquivos atinge um ponto em que a intervenção do usuário é necessária e os dados podem ser perdidos. O novo recurso de journaling fornecido pela GEOM pode ajudar bastante nesses cenários, praticamente eliminando o tempo necessário para a verificação do sistema de arquivos e garantindo que o sistema de arquivos seja rapidamente restaurado para um estado consistente. Este artigo descreve um procedimento para implementar o journaling do UFS em um cenário típico de PC de mesa (um único disco rígido usado para o sistema operacional e para os dados). Deve ser seguido durante uma nova instalação do FreeBSD. As etapas são simples o suficiente e não requerem interação excessivamente complexa com a linha de comando. Depois de ler este artigo, você saberá: * Como reservar espaço para o journaling durante uma nova instalação do FreeBSD. * Como carregar e ativar o módulo `geom_journal` (ou como compilar o suporte para ele em seu kernel customizado). * Como converter seus sistemas de arquivos existentes para utilizar o journaling e quais opções usar em [.filename]#/etc/fstab# para montá-los. * Como implementar o journaling em novas partições (vazias). * Como solucionar problemas comuns associados ao journaling. Antes de ler este artigo, você deve ser capaz de: * Entender os conceitos básicos do UNIX(R) e do FreeBSD. * Estar familiarizado com o procedimento de instalação do FreeBSD e com o utilitário sysinstall. [WARNING] ==== O procedimento descrito aqui é destinado a preparar uma nova instalação na qual ainda não temos nenhum dado real do usuário é armazenado no disco. Embora seja possível modificar e estender este procedimento para sistemas já em produção, você deve efetuar o _backup_ de todos os dados importantes antes de fazer isso. Mexer com discos e partições em um baixo nível pode levar a erros fatais e a perda de dados. ==== [[understanding-journaling]] == Compreendendo o journaling no FreeBSD O journaling fornecido pelo GEOM no FreeBSD 7._X_ não é específico do sistema de arquivos (diferentemente do sistema de arquivos ext3 no Linux(R)), funcionando a nível de bloco. Embora isso signifique que ele possa ser aplicado a sistemas de arquivos diferentes, no FreeBSD 7.0-RELEASE, ele só pode ser usado com o UFS2. Esta funcionalidade é fornecida pelo carregamento do módulo [.filename]#geom_journal.ko# no kernel (ou através da compilação de um kernel personalizado) e pelo uso do comando `gjournal` para configurar os sistemas de arquivos. Em geral, você gostaria de utilizar o journal em grandes sistemas de arquivos, como o [.filename]#/usr#. Você precisará no entanto (veja a seção seguinte) reservar algum espaço livre em disco para isso. Quando um sistema de arquivos é "journaled", é necessário algum espaço em disco para manter o próprio journal. O espaço em disco que contém os dados reais é chamado de __data provider__, enquanto o que contém o journal é chamado de __journal provider__. Os provedores de dados e de journal precisam estar em partições diferentes ao fazer o journaling de uma partição existente (não vazia). Ao fazer o journaling de uma nova partição, você tem a opção de usar um único provedor para os dados e o journal. Em todo caso, o comando `gjournal` combina os dois provedores para criar o sistema de arquivos journaled final. Por exemplo: * Você deseja fazer o journaling do seu sistema de arquivos [.filename]#/usr#, armazenado em [.filename]#/dev/ad0s1f# (que já contém dados). * Você reservou algum espaço livre no disco, na partição [.filename]#/dev/ad0s1g#. * Usando o comando `gjournal`, um novo dispositivo [.filename]#/dev/ad0s1f.journal# é criado no qual o [.filename]#/dev/ad0s1f# é o data provider, e o [.filename]#/dev/ad0s1g# é o journal provider. Este novo dispositivo é então usado para todas as operações de arquivo posteriores. A quantidade de espaço em disco que você precisa reservar para o journal provider depende da carga de uso do sistema de arquivos e não do tamanho do data provider. Por exemplo, em um desktop típico de escritório, um journal provider de 1 GB para o sistema de arquivos [.filename]#/usr# será suficiente, enquanto uma máquina que lida com I/O de disco pesado (por exemplo, edição de vídeo) pode precisar de mais. Um kernel panic ocorrerá se o espaço do journal estiver esgotado antes de ter a chance de ser committed. [NOTE] ==== É improvável que os tamanhos de journal sugeridos aqui causem problemas no uso típico de um desktop (como navegação na Web, processamento de texto e reprodução de arquivos de mídia). Se sua carga de trabalho incluir intensa atividade de disco, use a regra a seguir para obter a confiabilidade máxima: o tamanho da RAM deve caber em 30% do espaço do journal provider. Por exemplo, se o seu sistema tiver 1 GB de RAM, crie um journal provider de aproximadamente 3,3 GB. (Multiplique o tamanho total da sua RAM por 3.3 para obter o tamanho do journal). ==== Para mais informações sobre journaling, leia a página de manual do man:gjournal[8]. [[reserve-space]] == Etapas durante a instalação do FreeBSD === Reservando espaço para o journaling Normalmente, um desktop típico tem um disco rígido que armazena o sistema operacional e os dados do usuário. Indiscutivelmente, o esquema de particionamento padrão selecionado pelo sysinstall é mais ou menos adequado: Um desktop não precisa de uma grande partição [.filename]#/var#, enquanto o [.filename]#/usr# é alocado com a maior parte do espaço em disco, já que os dados do usuário e muitos pacotes são instalados em seus subdiretórios. O particionamento padrão (aquele obtido pressionando kbd:[A] no editor de partições do FreeBSD, chamado Disklabel) não deixa nenhum espaço não alocado. Cada partição que será journaled, requer outra partição para journal. Como a partição [.filename]#/usr# é a maior, faz sentido reduzir ligeiramente essa partição, para obter o espaço necessário para o journaling. No nosso exemplo, um disco de 80 GB é usado. A captura de tela a seguir mostra as partições padrões criadas por Disklabel durante a instalação: image::disklabel1.png[] Se isso é mais ou menos o que você precisa, é muito fácil se ajustar ao journaling. Simplesmente use as teclas de seta para mover o realce para a partição [.filename]#/usr# e pressione kbd:[D] para excluí-la. Agora, mova o realce para o nome do disco na parte superior da tela e pressione kbd:[C] para criar uma nova partição para [.filename]#/usr#. Esta nova partição deve ser menor em 1 GB (se você pretende registrar apenas [.filename]#/usr#), ou 2 GB (se você pretende registrar ambos [.filename]#/usr# e [.filename]#/var#). No pop-up exibido, opte por criar um sistema de arquivos e digite [.filename]#/usr# como o ponto de montagem. [NOTE] ==== Você deve fazer o journal da partição [.filename]#/var#? Normalmente, o journaling faz sentido em partições grandes. Você pode decidir não fazer o journal do [.filename]#/var#, embora fazê-lo em um desktop típico não cause nenhum dano. Se o sistema de arquivos é usado levemente (bastante provável para um desktop) você pode querer alocar menos espaço em disco para o seu journal. Em nosso exemplo, nós fizemos o journal em ambos [.filename]#/usr# e [.filename]#/var#. Você pode, naturalmente, ajustar o procedimento às suas próprias necessidades. ==== Para manter as coisas o mais fáceis o possível, vamos usar o sysinstall para criar as partições necessárias para o journaling. No entanto, durante a instalação, o sysinstall insiste em pedir um ponto de montagem para cada partição criada. Neste ponto, você não tem nenhum ponto de montagem para as partições que irão manter os journals, e na realidade você __nem precisa deles__. Estas não são partições que iremos montar em algum lugar. Para evitar esses problemas com o sysinstall, vamos criar as partições de journal como espaço de troca. O swap nunca é montado, e o sysinstall não tem problemas para criar tantas partições de troca quantas forem necessárias. Após a primeira reinicialização, o [.filename]#/etc/fstab# terá que ser editado, e as entradas extras do espaço de troca serão removidas. Para criar o swap, use novamente as teclas de seta para mover o realce para a parte superior da tela do Disklabel, para que o nome do disco seja realçado. Em seguida, pressione kbd:[N], insira o tamanho desejado (_1024M_) e selecione "swap space" no menu pop-up exibido. Repita para cada journal que você deseja criar. Em nosso exemplo, criamos duas partições para fornecer os diários de [.filename]#/usr# e [.filename]#/var#. O resultado final é mostrado na seguinte captura de tela: image::disklabel2.png[] Quando tiver concluído a criação das partições, sugerimos que você anote os nomes das partições e os pontos de montagem, para que possa consultar facilmente essas informações durante a fase de configuração. Isso ajudará a reduzir os erros que podem danificar sua instalação. A tabela a seguir mostra nossas anotações para a configuração de exemplo: .Partições e Journals [cols="1,1,1", options="header"] |=== | Partições | Ponto de montagem | Journal |ad0s1d |/var |ad0s1h |ad0s1f |/usr |ad0s1g |=== Continue a instalação como faria normalmente. No entanto, sugerimos que você adie a instalação de softwares de terceiros (pacotes) até que você configure completamente o journaling. [[first-boot]] === Inicializando pela primeira vez Seu sistema irá iniciar normalmente, mas você precisará editar o [.filename]#/etc/fstab# para remover as partições extras de swap que você criou para os journals. Normalmente, a partição swap que você irá usar é aquela com o sufixo "b" (por exemplo, ad0s1b no nosso exemplo). Remova todas as outras entradas de espaço swap e reinicialize para que o FreeBSD pare de usá-las. Quando o sistema voltar a funcionar, estaremos prontos para configurar o journaling. [[configure-journal]] == Configurando o journaling [[running-gjournal]] === Executando o `gjournal` Tendo preparado todas as partições requeridas, é bastante fácil configurar o journaling. Nós precisaremos mudar para o modo de single user, então entre como `root` e digite: [source,shell] .... # shutdown now .... Pressione kbd:[Enter] para obter o shell padrão. Nós precisaremos desmontar as partições que serão registradas no diário, no nosso exemplo [.filename]#/usr# e [.filename]#/var#: [source,shell] .... # umount /usr /var .... Carregue o módulo necessário para o journaling: [source,shell] .... # gjournal load .... Agora, use suas anotações para determinar qual partição será usada para cada diário. Em nosso exemplo, [.filename]#/usr# é [.filename]#ad0s1f# e seu journal será [.filename]#ad0s1g#, enquanto [.filename]#/var# é [.filename]#ad0s1d# e será journaled para [.filename]#ad0s1h#. Os seguintes comandos são necessários: [source,shell] .... # gjournal label ad0s1f ad0s1g GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. # gjournal label ad0s1d ad0s1h GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. .... [NOTE] ==== Se o último setor de qualquer partição for usado, o `gjournal` retornará um erro. Você terá que executar o comando usando o sinalizador `-f` para forçar uma substituição, ou seja: [source,shell] .... # gjournal label -f ad0s1d ad0s1h .... Como esta é uma nova instalação, é altamente improvável que qualquer coisa seja realmente sobrescrita. ==== Neste ponto, dois novos dispositivos são criados, a saber [.filename]#ad0s1d.journal# e [.filename]#ad0s1f.journal#. Os quais representam as partições [.filename]#/var# e [.filename]#/usr# que temos que montar. Antes de montar, devemos definir o flag de Journal e limpar o flag de Soft Updates: [source,shell] .... # tunefs -J enable -n disable ad0s1d.journal tunefs: gjournal set tunefs: soft updates cleared # tunefs -J enable -n disable ad0s1f.journal tunefs: gjournal set tunefs: soft updates cleared .... Agora, monte os novos dispositivos manualmente em seus respectivos locais (note que agora podemos usar a opção de montagem `async`): [source,shell] .... # mount -o async /dev/ad0s1d.journal /var # mount -o async /dev/ad0s1f.journal /usr .... Edite o [.filename]#/etc/fstab# e atualize as entradas para [.filename]#/usr# e [.filename]#/var#: [.programlisting] .... /dev/ad0s1f.journal /usr ufs rw,async 2 2 /dev/ad0s1d.journal /var ufs rw,async 2 2 .... [WARNING] ==== Certifique-se de que as entradas acima estão corretas ou você terá problemas para inicializar normalmente após o reboot! ==== Finalmente, edite o [.filename]#/boot/loader.conf# e adicione a seguinte linha para que o módulo man:gjournal[8] seja carregado em cada boot: [.programlisting] .... geom_journal_load="YES" .... Parabéns! Seu sistema está agora configurado para journaling. Você pode digitar `exit` para retornar ao modo multiusuário ou reinicializar para testar sua configuração (recomendado). Durante a inicialização, você verá mensagens como as seguintes: [source,shell] .... ad0: 76293MB XEC XE800JD-00HBC0 08.02D08 at ata0-master SATA150 GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal ad0s1d clean. GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal ad0s1f clean. .... Após um encerramento não limpo, as mensagens variam ligeiramente, ou seja: [source,shell] .... GEOM_JOURNAL: Journal ad0s1d consistent. .... Isso geralmente significa que o man:gjournal[8] usou as informações no journal provider para retornar o sistema de arquivos a um estado consistente. [[gjournal-new]] === Fazendo journaling de partições recém-criadas Embora o procedimento acima seja necessário para partições que fazem uso de journaling e que já contêm dados, o journaling de uma partição vazia é um pouco mais fácil, uma vez que os dados e o journal provider podem ser armazenados na mesma partição. Por exemplo, suponha que um novo disco tenha sido instalado e uma nova partição [.filename]#/dev/ad1s1d# tenha sido criada. Criar o journal seria tão simples quanto: [source,shell] .... # gjournal label ad1s1d .... O tamanho do journal será 1 GB por padrão. Você pode ajustá-lo usando a opção `-s`. O valor pode ser dado em bytes, ou acrescentado por `K`, `M` ou `G` para indicar Kilobytes, Megabytes ou Gigabytes, respectivamente. Note que o comando `gjournal` não permitirá que você crie journals de tamanhos pequenos e inadequados. Por exemplo, para criar um journal de 2 GB, você poderia usar o seguinte comando: [source,shell] .... # gjournal label -s 2G ad1s1d .... Você pode criar um sistema de arquivos em sua nova partição e ativar o journaling usando a opção `-J`: [source,shell] .... # newfs -J /dev/ad1s1d.journal .... [[configure-kernel]] === Adicionando suporte ao journaling no seu kernel personalizado Se você não deseja carregar o `geom_journal` como um módulo, você pode construir suas funções diretamente em seu kernel. Edite seu arquivo de configuração do kernel personalizado e verifique se ele inclui estas duas linhas: [.programlisting] .... options UFS_GJOURNAL # Note: This is already in GENERIC options GEOM_JOURNAL # You will have to add this one .... Recompile e reinstale seu kernel seguindo as instruções link:{handbook}#kernelconfig[relevantes no Handbook do FreeBSD]. Não se esqueça de remover a entrada relevante "load" do [.filename]#/boot/loader.conf# se você a usou anteriormente. [[troubleshooting-gjournal]] == Solução de problemas com journaling A seção a seguir aborda as perguntas mais frequentes relacionadas a problemas relacionados ao journaling. === Estou recebendo um kernel panic durante períodos de alta atividade de disco. Como isso está relacionado ao journaling? O journal provavelmente se enche antes que ele tenha a chance de ser enviado (descarregado) para o disco. Lembre-se de que o tamanho do journal depende da carga de uso e não do tamanho do provedor de dados. Se a atividade do disco for alta, você precisará de uma partição maior para o journal. Veja a nota na seção <>. === Eu cometi algum erro durante a configuração e não consigo inicializar normalmente agora. Isso pode ser resolvido de alguma forma? Você esqueceu (ou escreveu incorretamente) a entrada em [.filename]#/boot/loader.conf#, ou existem erros no seu arquivo [.filename]#/etc/fstab#. Estes erros geralmente são fáceis de corrigir. Pressione kbd:[Enter] para acessar o shell padrão do modo single user. Em seguida, localize a raiz do problema: [source,shell] .... # cat /boot/loader.conf .... Se a entrada `geom_journal_load` estiver ausente ou incorreta, os dispositivos registrados nunca serão criados. Carregue o módulo manualmente, monte todas as partições e continue com a inicialização do modo multi usuário: [source,shell] .... # gjournal load GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal. GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data. GEOM_JOURNAL: Journal ad0s1d clean. GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data. GEOM_JOURNAL: Journal ad0s1f clean. # mount -a # exit (boot continues) .... Se, por outro lado, esta entrada estiver correta, dê uma olhada em [.filename]#/etc/fstab#. Você provavelmente encontrará uma entrada incorreta ou faltando. Nesse caso, monte todas as partições restantes manualmente e continue com o boot em modo multi-usuários. === Posso remover o registro no journal e retornar ao meu sistema de arquivos padrão com o Soft Updates? Certo. Use o procedimento a seguir, que inverte as alterações. As partições que você criou para os provedores de journal podem ser usadas para outros propósitos, se você desejar. Faça login como `root` e alterne para o modo de usuário único: [source,shell] .... # shutdown now .... Desmonte as partições journaled: [source,shell] .... # umount /usr /var .... Sincronize os journals: [source,shell] .... # gjournal sync .... Pare os provedores de journaling: [source,shell] .... # gjournal stop ad0s1d.journal # gjournal stop ad0s1f.journal .... Limpe os metadados de journaling de todos os dispositivos usados: [source,shell] .... # gjournal clear ad0s1d # gjournal clear ad0s1f # gjournal clear ad0s1g # gjournal clear ad0s1h .... Limpe o sinalizador de journaling do sistema de arquivos e restaure a flag do Soft Updates: [source,shell] .... # tunefs -J disable -n enable ad0s1d tunefs: gjournal cleared tunefs: soft updates set # tunefs -J disable -n enable ad0s1f tunefs: gjournal cleared tunefs: soft updates set .... Remonte os dispositivos antigos à mão: [source,shell] .... # mount -o rw /dev/ad0s1d /var # mount -o rw /dev/ad0s1f /usr .... Edite o [.filename]#/etc/fstab# e restaure-o ao seu estado original: [.programlisting] .... /dev/ad0s1f /usr ufs rw 2 2 /dev/ad0s1d /var ufs rw 2 2 .... Finalmente, edite o [.filename]#/boot/loader.conf#, remova a entrada que carrega o módulo `geom_journal` e reinicie. [[further-reading]] == Leitura Adicional Journaling é um recurso relativamente novo do FreeBSD e, como tal, ainda não está muito bem documentado. Você pode, no entanto, encontrar as seguintes referências adicionais úteis: * Uma link:{handbook}geom-gjournal[nova seção sobre journaling] agora faz parte do Handbook do FreeBSD. * https://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html[Este post] em http://lists.FreeBSD.org/mailman/listinfo/freebsd-current[freebsd-current] pelo desenvolvedor do man:gjournal[8], Paweł Jakub Dawidek mailto:pjd@FreeBSD.org[pjd@FreeBSD.org]. * https://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html[Este post] em http://lists.FreeBSD.org/mailman/listinfo/freebsd-questions[freebsd-questions] por Ivan Voras mailto:ivoras@FreeBSD.org[ivoras@FreeBSD.org]. * As páginas de manual do man:gjournal[8] e man:geom[8]. diff --git a/documentation/content/pt-br/articles/hubs/_index.adoc b/documentation/content/pt-br/articles/hubs/_index.adoc index c98c5209ac..8658d9f111 100644 --- a/documentation/content/pt-br/articles/hubs/_index.adoc +++ b/documentation/content/pt-br/articles/hubs/_index.adoc @@ -1,296 +1,306 @@ --- title: Espelhando o FreeBSD authors: - author: Jun Kuriyama email: kuriyama@FreeBSD.org - author: Valentino Vaschetto email: logo@FreeBSD.org - author: Daniel Lang email: dl@leo.org - author: Ken Smith email: kensmith@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Espelhando o FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Um artigo em andamento sobre como espelhar o FreeBSD, destinado à administradores de hubs. ''' toc::[] [NOTE] ==== Nós não estamos aceitando novos sites espelho neste momento. ==== [[mirror-contact]] == Informações de contato Os Coordenadores do Sistema de Espelhamento podem ser contatados pelo email mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org]. Existe também uma http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[lista de discussão de sites espelho do FreeBSD]. [[mirror-requirements]] == Requisitos para um site espelho do FreeBSD [[mirror-diskspace]] === Espaço em disco O espaço em disco é um dos requisitos mais importantes. Dependendo do conjunto de releases, arquiteturas e grau de cobertura que você deseja espelhar, uma quantidade enorme de espaço em disco pode ser consumida. Também tenha em mente que espelhos _oficiais_ provavelmente precisam ser completos. As páginas web devem ser sempre espelhadas completamente. Observe também que os números indicados aqui refletem o estado atual (para 10.4-RELEASE/11.2-RELEASE). Desenvolvimentos adicionais e novas releases só aumentarão a quantidade necessária. Também certifique-se de ter algum espaço extra (cerca de 10-20%) apenas para ter certeza de que não irá faltar espaço. Aqui estão alguns números aproximados: * Distribuição FTP completa: 1.4 TB * Deltas do CTM: 10 GB * Páginas Web: 1GB O uso atual de disco da Distribuição por FTP pode ser encontrado em link:ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes[ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes]. [[mirror-bandwidth]] === Conexão de Rede/Largura de Banda Claro, você precisa estar conectado à Internet. A largura de banda necessária depende do uso pretendido do site espelho. Se você quiser espelhar apenas algumas partes do FreeBSD para uso na sua rede local/intranet, a demanda pode ser muito menor do que se você quiser disponibilizar os arquivos publicamente. Se você pretende se tornar um site espelho oficial, a largura de banda necessária será ainda maior. Podemos apenas dar estimativas aproximadas aqui: * Site local, sem acesso público: basicamente sem valor mínimo, mas se for menor que < 2 Mbps, pode deixar a sincronização bem lenta. * Site público não oficial: 34 Mbps é provavelmente um bom começo. * Site oficial: > 100 Mbps é recomendado, e seu host deve estar conectado o mais próximo possível do seu roteador de borda. [[mirror-system]] === Requisitos de Sistema, CPU, RAM Isto depende muito do número esperado de clientes, que é determinado pela política do servidor. O dimensionamento também é afetado pelo tipo de serviços que você deseja oferecer. Serviços FTP ou HTTP simples podem não exigir uma quantidade enorme de recursos. Tenha cuidado se você fornecer o rsync. Isso pode ter um grande impacto nos requisitos de CPU e memória, já que este serviço é considerado um devorador de memória. Os exemplos a seguir, visam lhe dar uma ideia simples deste dimensionamento. Para um site com visitação moderada o qual ofereça o serviço de rsync, você pode considerar uma CPU entre 800 MHz - 1 GHz, e pelo menos 512 MB de memória RAM. Esta é provavelmente a configuração mínima para um site espelho __oficial__. Para um site com visitação frequente, você definitivamente vai precisar de mais memória RAM (considere 2 GB como um bom ponto de partida) e possivelmente de mais poder de processamento (CPU), o que pode significar que você precisará ir para um sistema multiprocessado (SMP). Você também pode querer considerar um subsistema de disco rápido. As operações no repositório SVN requerem um subsistema de disco rápido (o RAID é altamente recomendado). Um controlador SCSI que possua um cache próprio também pode acelerar as coisas, já que a maioria desses serviços incorrem em um grande número de pequenas modificações no disco. [[mirror-services]] === Serviços para oferecer Todo site espelho é obrigado a disponibilizar um conjunto de serviços básicos. Em adição a estes serviços obrigatórios, existe um grande número de serviços opcionais aos quais o administrador do servidor pode optar por oferecer. Esta sessão irá detalhar quais serviços você pode oferecer, bem como implementá-los. [[mirror-serv-ftp]] ==== FTP (necessário para o conjunto de arquivos do FTP) Este é um dos serviços mais básicos, e ele é obrigatório em todos os sites espelhos que oferecem acesso público às distribuições via FTP. O acesso ao FTP deve ser anônimo, e não é permitido o uso de nenhum controle nas taxas de upload/download (o que seria uma coisa ridícula de qualquer maneira). Não é necessário ter o upload de arquivos habilitado (e isso _nunca_ deve ser permitido na área onde os arquivos do FreeBSD são mantidos). Os arquivos do FreeBSD devem ficar disponíveis sob o caminho [.filename]#/pub/FreeBSD#. Existem diversos softwares disponíveis que podem ser configurados para operar como um servidor de FTP anônimo. Por exemplo (em ordem alfabética) * `/usr/libexec/ftpd`: o próprio ftpd do FreeBSD pode ser usado. Não deixe de ler o manual do man:ftpd[8]. * package:ftp/ncftpd[]: Um pacote comercial, grátis para uso educacional. * package:ftp/oftpd[]: Um ftpd projetado tendo a segurança como foco principal. * package:ftp/proftpd[]: Um ftpd modular e muito flexível. * package:ftp/pure-ftpd[]: Outro ftpd desenvolvido com segurança em mente. * package:ftp/twoftpd[]: Mais um ftpd desenvolvido com segurança em mente. * package:ftp/vsftpd[]: Um ftpd "muito seguro". O ftpd nativo do FreeBSD, o proftpd, e talvez o ncftpd são alguns dos servidores de FTP mais utilizados. Os demais não possuem uma grande base de usuários entre os sites espelhos. Um item a ser considerado é que você pode precisar de flexibilidade para controlar quantas conexões simultâneas serão permitidas no servidor, limitando desta forma o consumo do seu link IP e dos demais recursos do sistema. [[mirror-serv-rsync]] ==== Rsync (opcional para o conjunto de arquivos do FTP) O rsync é muitas vezes oferecido para acesso ao conteúdo da área de FTP de um site espelho do FreeBSD, desta forma outros sites espelhos podem utilizar o seu sistema como fonte para se espelhar. O protocolo do rsync é diferente do FTP em muitos aspectos. Ele é muito mais amigável em relação ao consumo de banda IP, uma vez que quando um arquivo é alterado ao invés de transferí-lo por completo novamente, ele transfere apenas as diferenças entre as duas versões do arquivo. O rsync requer uma grande quantidade de memória para cada instância. A quantidade de memória alocada depende do tamanho do modulo sincronizado em termos do número de diretórios e de arquivos. O rsync pode utilizar `rsh` e o `ssh` (que agora é padrão) para transporte dos dados, ou então utilizar o seu próprio protocolo para acesso stand-alone (este é o método preferido para um servidor público de Rsync). Obrigatoriedade de autenticação, limites ao número de conexões simultâneas e outras restrições podem ser aplicadas. Há apenas um pacote de software disponível para se implementar um servidor de Rsync: * package:net/rsync[] [[mirror-serv-http]] ==== HTTP (necessário para as páginas web, opcional para o conjunto de arquivos do FTP) Se você deseja disponibilizar as páginas web do FreeBSD, você vai precisar instalar um servidor web. Opcionalmente você poderá oferecer acesso a sua árvore de FTP via HTTP. A escolha do software do servidor web é uma escolha do administrador do site espelho. As opções mais populares são: * package:www/apache24[]: O Apache é o servidor web mais amplamente utilizado na internet. Ele é usado extensivamente pelo projeto FreeBSD. * package:www/boa[]: O Boa é um servidor HTTP single-task. Ao contrário dos servidores Web tradicionais, o seu processo não se divide para cada conexão de entrada e nem cria muitas cópias de si mesmo para lidar com várias conexões. Entretanto, ele fornece um desempenho excelente para conteúdo puramente estático. * package:www/cherokee[]: O >Cherokee é um servidor web muito rápido, flexível e fácil de configurar. Ele suporta as tecnologias difundidas atualmente: FastCGI, SCGI, PHP, CGI, conexões criptografadas por SSL/TLS, vhosts, autenticação de usuários, codificação on the fly e balanceamento de carga. Ele também gera arquivos de log compatíveis com o Apache. * package:www/lighttpd[]: O lighttpd é um servidor web seguro, rápido, compatível com os padrões e muito flexível o qual foi otimizado para ambientes de alto desempenho. Tem um consumo de memória muito baixo em comparação com outros servidores Web, bem como um baixo consumo de CPU. * package:www/nginx[]: O nginx é um servidor web de alto desempenho com baixo consumo de memória e recursos-chave para construir uma infraestrutura web moderna e eficiente. Os recursos incluem um servidor HTTP, proxy reverso de HTTP e email, armazenamento em cache, balanceamento de carga, compactação, limitação de solicitações, multiplexação e reutilização de conexões, descarregamento de SSL e streaming de mídia por HTTP. * package:www/thttpd[]: Se você estiver servindo uma grande quantidade de conteúdo estático, você pode descobrir que usar uma aplicação como o thttpd é mais eficiente do que outros servidores web. Ele também é otimizado para ter um excelente desempenho no FreeBSD. [[mirror-howto]] == Como espelhar o FreeBSD Ok, agora você conhece os requisitos e sabe como oferecer os serviços, mas não sabe como obtê-los. :-) Esta seção explica como realmente espelhar as várias partes do FreeBSD, quais ferramentas utilizar e de onde espelhar. [[mirror-ftp-rsync]] === Espelhando o site FTP A área FTP possui a maior quantidade de dados a serem espelhados. Ela inclui os _conjuntos de distribuição_ necessários para a instalação em rede, os _branches_ que são snapshots das árvores de código fonte, as _Imagens ISO_ para gravar CD-ROMs com a distribuição de instalação, um sistema de arquivos ativo e um snapshot da árvore de ports. E claro, tudo isso para as várias versões do FreeBSD e diversas arquiteturas. A melhor maneira de espelhar a área FTP é com o rsync. Você pode instalar o port package:net/rsync[] e então usar o rsync para sincronizar com seu host upstream. O rsync já foi mencionado em <>. Como o acesso rsync não é necessário, seu site de upstream preferido pode não permitir isso. Talvez você precise procurar um pouco mais para localizar um site que permita acesso por rsync. [NOTE] ==== Como o número de clientes rsync terá um impacto significativo na performance do servidor, a maioria dos administradores impõe limitações em seus servidores. Para um espelho, você deve perguntar ao mantenedor do site com o qual você está sincronizando sobre sua política, e talvez pedir uma exceção para o seu host (já que você também é um site espelho). ==== Um exemplo de linha de comando para espelhar o FreeBSD pode ser verificada abaixo: [source,shell] .... % rsync -vaHz --delete rsync://ftp4.de.FreeBSD.org/FreeBSD/ /pub/FreeBSD/ .... Consulte a documentação do rsync, que também está disponível em http://rsync.samba.org/[http://rsync.samba.org/], sobre as várias opções a serem usadas com o rsync. Se você sincronizar o módulo inteiro (diferentemente dos subdiretórios), esteja ciente de que o diretório do módulo (aqui "FreeBSD") não será criado, então você não pode omitir o diretório de destino. Além disso, você pode querer configurar um script que chame tal comando via man:cron[8]. [[mirror-www]] === Espelhando as páginas WWW O site do FreeBSD deve ser espelhado apenas via rsync. Uma linha de comando para espelhar o site do FreeBSD pode parecer com: [source,shell] .... % rsync -vaHz --delete rsync://bit0.us-west.freebsd.org/FreeBSD-www-data/ /usr/local/www/ .... [[mirror-pkgs]] === Espelhando os Pacotes Devido a exigências muito altas de largura de banda, armazenamento e administração, o Projeto FreeBSD decidiu não permitir espelhos públicos de pacotes. Para sites com muitas máquinas, pode ser vantajoso executar um proxy HTTP para fazer cache do man:pkg[8]. Alternativamente, pacotes específicos e suas dependências podem ser baixados executando algo assim: [source,shell] .... % pkg fetch -d -o /usr/local/mirror vim .... Quando esses pacotes forem baixados, os metadados do repositório devem ser gerados executando: [source,shell] .... % pkg repo /usr/local/mirror .... Uma vez que os pacotes tenham sido baixados e os metadados para o repositório tenham sido gerados, sirva os pacotes até as máquinas clientes via HTTP. Para obter informações adicionais, consulte as páginas de manual do man:pkg[8], mais especificamente a página man:pkg-repo[8]. [[mirror-how-often]] === Com que frequência eu devo atualizar o conteúdo do meu espelho? Todo site espelho deve ser atualizado no mínimo uma vez por dia. Certamente, um script com bloqueio para impedir que várias execuções ocorram ao mesmo tempo será necessário para executar a partir do man:cron[8]. Como quase todo administrador faz isso à sua maneira, instruções específicas não podem ser fornecidas. Mas poderia ser algo como: [.procedure] . Coloque o comando para executar seu aplicativo de espelhamento em um script. Recomenda-se o uso de um script simples `/bin/sh`. . Adicione alguns redirecionamentos de saída para que as mensagens de diagnóstico sejam registradas em um arquivo. . Teste se o seu script funciona. Verifique os logs. . Use o man:crontab[1] para adicionar o script ao man:crontab[5] do usuário apropriado. Este deve ser um usuário diferente daquele sob o qual o daemon FTP está sendo executado, de forma que, se as permissões de arquivo dentro de sua área FTP não forem legíveis por todos, esses arquivos não poderão ser acessados ​​por FTP anônimo. Isto é usado para fazer o "stage" de uma release - assegurando que todos os sites espelhos oficiais tenham todos os arquivos necessários da release no dia do lançamento. Aqui estão alguns agendamentos recomendados: * Conjunto de arquivos FTP: diariamente * Páginas WWW: diariamente [[mirror-where]] == De onde espelhar Esta é uma questão importante. Então, esta seção vai gastar algum esforço para explicar mais a fundo. Nós diremos isso várias vezes: sob nenhuma circunstância você deve espelhar a partir do `ftp.FreeBSD.org`. [[mirror-where-organization]] === Algumas palavras sobre a organização Os espelhos são organizados por país. Todos os espelhos oficiais possuem uma entrada de DNS no formato `ftpN.CC.FreeBSD.org`. O _CC_ (ou seja, o código do país) é o _domínio de nível superior_ (TLD) do país onde esse espelho está localizado. _N_ é um número, dizendo que o host seria o espelho _Nth_ daquele país. (O mesmo se aplica a `wwwN.CC.FreeBSD.org`, etc.) Há espelhos sem partes __CC__. Esses são os sites espelhos que são muito bem conectados e permitem um grande número de usuários simultâneos. O `ftp.FreeBSD.org` é na verdade duas máquinas, uma atualmente localizada na Dinamarca e outra nos Estados Unidos. Este _NÃO_ é um site mestre e nunca deve ser usado para se espelhar. Muitos documentos on-line conduzem os usuários "interativos" para `ftp.FreeBSD.org`, portanto os sistemas automatizados de espelhamento devem utilizar uma máquina diferente para se espelhar. Além disso, existe uma hierarquia de espelhos, descrita em termos de __camadas__. Os sites mestres não são referenciados, mas podem ser descritos como __Tier-0__. Espelhos que espelham desses sites podem ser considerados __Tier-1__, espelhos de __Tier-1__mirrors, são__Tier-2__, etc. Os sites oficiais são encorajados a ter um _nível_ baixo, mas quanto mais baixo o nível, maiores os requisitos em termos, conforme descrito em <>. Também o acesso a espelhos de baixo nível pode ser restrito, e o acesso a sites mestres é definitivamente restrito. A __tier__-hierarchy não é refletida pelo DNS e geralmente não é documentada em nenhum lugar, exceto nos sites mestres. No entanto, os espelhos oficiais com números baixos como 1-4, geralmente são _Tier-1_ (isso é apenas uma dica, e não há regra). [[mirror-where-where]] === Ok, mas de onde devo baixar os arquivos agora? Em nenhuma circunstância você deve espelhar a partir de `ftp.FreeBSD.org`. A resposta simples é: do site que está mais próximo de você em termos de Internet ou que lhe ofereça o acesso mais rápido. [[mirror-where-simple]] ==== Eu só quero espelhar de algum lugar! Se você não tem nenhuma intenção ou requisito especial, a declaração em <> se aplica. Isso significa: [.procedure] . Verifique quais fornecem acesso mais rápido (número de saltos, tempos de ida e volta) e ofereçam os serviços que você pretende usar (como rsync). . Entre em contato com os administradores do site escolhido, informando sua solicitação e perguntando sobre seus termos e políticas. . Configure o seu espelho conforme descrito acima. [[mirror-where-official]] ==== Eu sou um espelho oficial, qual é o site certo para mim? Em geral, a descrição em <> ainda se aplica. É claro que você pode querer colocar algum peso no fato de que seu upstream deve ser de nível baixo. Existem algumas outras considerações sobre os espelhos _oficiais_ que são descritos em <>. [[mirror-where-master]] ==== Eu quero acessar os sites principais! Se você tiver boas razões e pré-requisitos, poderá querer e obter acesso a um dos sites mestres. O acesso a esses sites é geralmente restrito e existem políticas especiais para acesso. Se você já é um espelho __oficial__, isso certamente irá ajudar você a obter acesso. Em qualquer outro caso, certifique-se de que seu país realmente precisa de outro espelho. Se já tiver três ou mais, pergunte ao "administrador de região"(mailto:hostmaster@CC.FreeBSD.org[hostmaster@CC.FreeBSD.org]) ou http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[Listas de discussão de sites espelho do FreeBSD] primeiro. Quem ajudou você a se tornar um espelho _oficial_ deve ajudar você a obter acesso a um host de upstream apropriado, seja um dos sites mestres ou um site Tier-1 adequado. Caso contrário, você pode enviar um email para mailto:mirror-admin@FreeBSD.org[mirror-admin@FreeBSD.org] para solicitar ajuda com isso. Existe um site principal para o conjunto de arquivos FTP. [[mirror-where-master-ftp]] ===== ftp-master.FreeBSD.org Este é o site principal do conjunto de arquivos FTP. O `ftp-master.FreeBSD.org` fornece acesso por rsync, além do acesso normal por FTP. Consulte <>. Os espelhos também são encorajados a permitir acesso por rsync para o conteúdo FTP, já que eles são espelhos de __Tier-1__. [[mirror-official]] == Espelhos Oficiais Espelhos oficiais são os espelhos que * a) tem uma entrada de DNS `FreeBSD.org` (geralmente um CNAME). * b) são listados como um espelho oficial na documentação do FreeBSD (como no Handbook). Até agora, para distinguir espelhos oficiais. Espelhos oficiais não são necessariamente espelhos __Tier-1__. No entanto, você provavelmente não encontrará um espelho _Tier-1_ que também não é oficial. [[mirror-official-requirements]] === Requisitos especiais para sites espelhos oficiais (Tier-1) Não é tão fácil declarar os requisitos para todos os sites espelhos oficiais, uma vez que o projeto é um pouco tolerante aqui. É mais fácil dizer o que um _site espelho oficial Tier-1_ precisa ter. Todos os outros sites espelhos oficiais podem considerar isto como um grande __deve__. Os sites espelhos Tier-1 precisam: * ter o conjunto completo de arquivos * permitir acesso a outros sites espelho * fornecer acesso por FTP e rsync Além disso, os administradores devem estar inscritos nas http://lists.FreeBSD.org/mailman/listinfo/freebsd-hubs[listas de discussão de sites espelho do FreeBSD]. Consulte link:{handbook}#eresources-mail[este link] para obter detalhes em como se inscrever. [IMPORTANT] ==== É _muito_ importante para um administrador de hub, especialmente administradores de hub de Tier-1, verificar o https://www.FreeBSD.org/releng/[calendário de lançamentos] para a próxima versão do FreeBSD. Isto é importante porque lhe dirá quando o próximo lançamento está programado para sair, e assim lhe dará tempo para se preparar para o grande pico de tráfego que virá. Também é importante que os administradores do hub tentem manter seus espelhos o mais atualizados possível (novamente, ainda mais importante para os espelhos Tier-1). Se o Mirror1 não for atualizado por um tempo, os espelhos de camada inferior começarão a espelhar os dados antigos do Mirror1 e, portanto, iniciará uma espiral descendente... Mantenha seus espelhos atualizados! ==== [[mirror-official-become]] === Como se tornar um site espelho oficial? Não estamos aceitando novos sites espelhos neste momento. [[mirror-statpages]] == Algumas estatísticas dos sites espelho Aqui estão os links para as páginas de estatísticas dos seus sites espelho favoritos (também conhecidos como os únicos que têm a boa vontade de fornecer as estatísticas). [[mirror-statpagesftp]] === Estatísticas do site FTP * ftp.is.FreeBSD.org - mailto:hostmaster@is.FreeBSD.org[hostmaster@is.FreeBSD.org] - http://www.rhnet.is/status/draupnir/draupnir.html[(Largura de Banda)] http://www.rhnet.is/status/ftp/ftp-notendur.html[(Processos FTP)] http://www.rhnet.is/status/ftp/http-notendur.html[(Processos HTTP)] * ftp2.ru.FreeBSD.org - mailto:mirror@macomnet.ru[mirror@macomnet.ru] - http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html[(Largura de Banda)] http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html[(Usuários HTTP e FTP)] diff --git a/documentation/content/pt-br/articles/ipsec-must/_index.adoc b/documentation/content/pt-br/articles/ipsec-must/_index.adoc index 207ba80215..5297be98e7 100644 --- a/documentation/content/pt-br/articles/ipsec-must/_index.adoc +++ b/documentation/content/pt-br/articles/ipsec-must/_index.adoc @@ -1,263 +1,273 @@ --- title: Verificação Independente da Funcionalidade IPsec no FreeBSD authors: - author: David Honig email: honig@sprynet.com releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "opengroup", "general"] --- = Verificação Independente da Funcionalidade IPsec no FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Você instalou o IPsec e ele parece estar funcionando. Como você sabe? Eu descrevo um método para verificar experimentalmente se o IPsec está funcionando. ''' toc::[] [[problem]] == O problema Primeiro, vamos assumir que você tem o <>. Como você sabe que ele está <>? Claro, sua conexão não funcionará se ele estiver mal configurado, e funcionará quando você finalmente acertar a configuração. O man:netstat[1]irá listá-lo. Mas você pode confirmar isso de forma independente? [[solution]] == A solução Em primeiro lugar, vejamos alguma informação teórica relevante em relação à criptografia: . Dados criptografados são uniformemente distribuídos, ou seja, possuem entropia máxima por símbolo; . Os dados brutos, não comprimidos são tipicamente redundantes, isto é, possuem entropia submáxima. Suponha que você possa medir a entropia dos dados destinados para a sua interface de rede e também dos dados originados dela. Então você pode ver a diferença entre dados não criptografados e dados criptografados. Isso seria verdade mesmo que alguns dos dados no "modo criptografado" não estivessem criptografados --- como deve o cabeçalho IP mais externo para que o pacote seja roteável. [[MUST]] === MUST O teste de "Estatística Universal para Geradores de Bits Aleatórios" de Ueli Maurer (https://web.archive.org/web/20011115002319/http://www.geocities.com/SiliconValley/Code/4704/universal.pdf[MUST ]) mede rapidamente a entropia de uma amostra. Ele usa um algoritmo semelhante à compressão. <> para uma variante que mede partes sucessivas (aproximadamente um quarto de megabyte) de um arquivo. [[tcpdump]] === Tcpdump Também precisamos de uma maneira de capturar os dados brutos da rede. Um programa chamado man:tcpdump[1] permite que você faça isso, se você ativou a interface _Berkeley Packet Filter_ no seu <>. O comando: [source,shell] .... tcpdump -c 4000 -s 10000 -w dumpfile.bin .... irá capturar 4000 pacotes brutos no arquivo _dumpfile.bin_. Até 10.000 bytes por pacote serão capturados neste exemplo. [[experiment]] == O Experimento Aqui está o experimento: [.procedure] . Abra uma janela para um host IPsec e outra janela para um host inseguro. . Agora comece a <>. . Na janela "segura", execute o comando UNIX(R) man:yes[1], que transmitirá o caractere `y`. Depois de um tempo, pare com isso. Alterne para a janela insegura e repita. Depois de um tempo, pare. . Agora execute o <> nos pacotes capturados. Você deve ver algo como o seguinte. O importante é notar que a conexão segura tem 93% (6,7) do valor esperado (7,18), e a conexão "normal" tem 29% (2,1) do valor esperado. + [source,shell] .... % tcpdump -c 4000 -s 10000 -w ipsecdemo.bin % uliscan ipsecdemo.bin Uliscan 21 Dec 98 L=8 256 258560 Measuring file ipsecdemo.bin Init done Expected value for L=8 is 7.1836656 6.9396 -------------------------------------------------------- 6.6177 ----------------------------------------------------- 6.4100 --------------------------------------------------- 2.1101 ----------------- 2.0838 ----------------- 2.0983 ----------------- .... [[caveat]] == Embargo Esta experiência mostra que o IPsec _parece_ estar distribuindo os dados de carga __uniformemente__, como a criptografia deveria. No entanto, o experimento descrito aqui _não pode_ detectar muitas das falhas possíveis em um sistema (nenhum dos quais eu tenho qualquer evidência para). Estes incluem geração ou troca deficiente de chaves, dados ou chaves sendo visíveis para outros, uso de algoritmos fracos, subversão do kernel, etc. Estude a fonte; conheça o código. [[IPsec]] == IPsec --- Definição Extensões de segurança do protocolo Internet para o IPv4; obrigatório para o IPv6. Um protocolo para negociar criptografia e autenticação no nível IP (host para host). O SSL protege apenas um soquete de aplicativo; O SSH protege apenas um login; PGP protege apenas um arquivo ou mensagem especifico. O IPsec criptografa tudo entre dois hosts. [[ipsec-install]] == Instalando o IPsec A maioria das versões modernas do FreeBSD tem suporte a IPsec em sua fonte base. Portanto, você precisará incluir a opção `IPSEC` em sua configuração de kernel e, após a reconstrução e reinstalação do kernel, configurar as conexões IPsec usando o comando man:setkey[8]. Um guia completo sobre como executar o IPsec no FreeBSD é fornecido no link:{handbook}#ipsec[Handbook do FreeBSD]. [[kernel]] == src/sys/i386/conf/KERNELNAME Isto precisa estar presente no arquivo de configuração do kernel para habilitar o suporte para captura de dados de rede com o man:tcpdump[1]. Certifique-se de executar o man:config[8] depois de adicionar a linha, de recompilar e de reinstalar. [.programlisting] .... device bpf .... [[code]] == Teste Estatístico Universal de Maurer (para tamanho de bloco = 8 bits) Você pode encontrar o mesmo código em https://web.archive.org/web/20031204230654/http://www.geocities.com:80/SiliconValley/Code/4704/uliscanc.txt[neste link]. [.programlisting] .... /* ULISCAN.c ---blocksize of 8 1 Oct 98 1 Dec 98 21 Dec 98 uliscan.c derived from ueli8.c This version has // comments removed for Sun cc This implements Ueli M Maurer's "Universal Statistical Test for Random Bit Generators" using L=8 Accepts a filename on the command line; writes its results, with other info, to stdout. Handles input file exhaustion gracefully. Ref: J. Cryptology v 5 no 2, 1992 pp 89-105 also on the web somewhere, which is where I found it. -David Honig honig@sprynet.com Usage: ULISCAN filename outputs to stdout */ #define L 8 #define V (1< #include int main(argc, argv) int argc; char **argv; { FILE *fptr; int i,j; int b, c; int table[V]; double sum = 0.0; int iproduct = 1; int run; extern double log(/* double x */); printf("Uliscan 21 Dec 98 \nL=%d %d %d \n", L, V, MAXSAMP); if (argc < 2) { printf("Usage: Uliscan filename\n"); exit(-1); } else { printf("Measuring file %s\n", argv[1]); } fptr = fopen(argv[1],"rb"); if (fptr == NULL) { printf("Can't find %s\n", argv[1]); exit(-1); } for (i = 0; i < V; i++) { table[i] = 0; } for (i = 0; i < Q; i++) { b = fgetc(fptr); table[b] = i; } printf("Init done\n"); printf("Expected value for L=8 is 7.1836656\n"); run = 1; while (run) { sum = 0.0; iproduct = 1; if (run) for (i = Q; run && i < Q + K; i++) { j = i; b = fgetc(fptr); if (b < 0) run = 0; if (run) { if (table[b] > j) j += K; sum += log((double)(j-table[b])); table[b] = i; } } if (!run) printf("Premature end of file; read %d blocks.\n", i - Q); sum = (sum/((double)(i - Q))) / log(2.0); printf("%4.4f ", sum); for (i = 0; i < (int)(sum*8.0 + 0.50); i++) printf("-"); printf("\n"); /* refill initial table */ if (0) { for (i = 0; i < Q; i++) { b = fgetc(fptr); if (b < 0) { run = 0; } else { table[b] = i; } } } } } .... diff --git a/documentation/content/pt-br/articles/linux-users/_index.adoc b/documentation/content/pt-br/articles/linux-users/_index.adoc index e68fc61748..e086fdf26a 100644 --- a/documentation/content/pt-br/articles/linux-users/_index.adoc +++ b/documentation/content/pt-br/articles/linux-users/_index.adoc @@ -1,326 +1,336 @@ --- title: Guia rápido de FreeBSD para usuários de Linux authors: - author: John Ferrell copyright: 2008 Projeto de Documentação do FreeBSD releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "intel", "redhat", "linux", "unix", "general"] --- = Guia rápido de FreeBSD para usuários de Linux :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este documento tem a intenção de familiarizar rapidamente usuários intermediários ou avançados do Linux(R) com o básico do FreeBSD. ''' toc::[] [[intro]] == Introdução Esse documento destaca algumas diferenças técnicas entre o FreeBSD e o Linux(R) para que os usuários intermediários ou avançados do Linux(R) possam se familiarizar rapidamente com o básico do FreeBSD. Este documento assume que o FreeBSD já está instalado. Acesse o link do capítulo link:{handbook}#bsdinstall[Instalando o FreeBSD] no Handbook do FreeBSD para obter ajuda no processo de instalação. [[shells]] == Shell Padrão Os usuários do Linux(R) são geralmente surpreendidos quando descobrem que o Bash não é o shell padrão do FreeBSD. De fato, o Bash não é incluído na instalação padrão. Ao invés disto, o FreeBSD usa o man:tcsh[1] como shell padrão para o usuário root, e o man:sh[1], um shell compatível com o Bourne shell, como shell padrão para os demais usuários. O man:sh[1] é muito similar ao Bash mas com um conjunto de funcionalidades muito menor. Geralmente os scripts shell escritos para o man:sh[1] irão ser executados no Bash, mas o contrário não. Entretanto, o Bash e outros shells estão disponíveis para a instalação usando a link:{handbook}#ports[Coleção de Pacotes e a Árvore de Ports]. Depois de instalar um novo shell, use o comando man:chsh[1] para trocar o shell padrão do usuário. É recomendado que o shell padrão do usuário `root` se mantenha inalterado uma vez que os shells que não fazem parte da base do sistema são instalados em [.filename]#/usr/local/bin#. No caso de ocorrer algum problema com o sistema de arquivos onde o diretório [.filename]#/usr/local/bin# está localizado e este não puder ser utilizado, o usuário `root` poderá não ter acesso ao shell padrão, evitando que o usuário `root` entre no sistema para corrigir o problema. [[software]] == Coleção de Pacotes e Árvore de Ports: Instalando novos programas no FreeBSD FreeBSD provê dois métodos para a instalação de novos aplicativos: pacotes binários e através da compilação do código fonte (Árvore de ports). Cada método tem seu benefício: .Pacotes Binários * Instalação rápida quando comparada com a compilação de grandes aplicativos . * Não há a necessidade de compreender como compilar um software. * Não é necessário a instalação de um compilador. .Árvore de Ports * Possibilidade de customizar as opções de instalação * Possibilidade de se aplicar patchs customizados Se a instalação da aplicação não necessitar de opções customizadas, a instalação via pacotes é suficiente. Compile o port sempre que o aplicativo exigir a personalização das opções padrão. Se você necessita de pacotes customizados, você poderá obtê-los através da compilação a partir do ports utilizando o comando `make Pacotes`. A lista completa da árvore de ports e dos pacotes pode ser encontrada https://www.freebsd.org/ports/[aqui]. [[packages]] === Pacotes Pacotes são aplicações pré-compiladas, os equivalentes no FreeBSD aos arquivos [.filename]#.deb# nos sistemas baseados no Debian/Ubuntu e aos arquivos [.filename]#.rpm# nos sistemas baseados no Fedora/Red Hat. Pacotes são instalados através do comando `pkg`. Por exemplo, o comando a seguir instala o Apache 2.4: [source,shell] .... # pkg install apache24 .... Para mais informações sobre pacotes, veja a seção 5.4 do Handbook do FreeBSD: link:{handbook}#pkgng-intro[Usando pkgng para gerenciar pacotes binários]. [[ports]] === Árvore de Ports A árvore de ports do FreeBSD é um framework de [.filename]##Makefiles##s e patches customizados especificamente para a instalação através do código fonte no FreeBSD. Quando um port é instalado, o sistema irá buscar o código fonte, aplicar qualquer patch que seja necessário, compilar o código, instalar a aplicação e qualquer outra dependência da qual ela necessite. A Coleção de Ports, algumas vezes referenciada como a árvore de ports, pode ser instalada em [.filename]#/usr/ports# usando o comando man:portsnap[8] (se estiver rodando FreeBSD 11.4 ou 12.1) ou Subversion (se estiver rodando FreeBSD-CURRENT). Instruções detalhadas para instalação da Coleção de Ports podem ser encontradas na link:{handbook}#ports-using[seção 5.5] do Handbook do FreeBSD. Para compilar um port, mude para o diretório do port e inicie o processo de compilação. O exemplo abaixo instala o Apache 2.4 através da Coleção de Ports: [source,shell] .... # cd /usr/ports/www/apache24 # make install clean .... Um dos benefícios de usar a árvore de ports para realizar a instalação de um software é a possibilidade de customizar as opções de instalação. O exemplo a seguir, especifica que o módulo mod_ldap também deve ser instalado: [source,shell] .... # cd /usr/ports/www/apache24 # make WITH_LDAP="YES" install clean .... Veja link:{handbook}#ports-using[Usando a Coleção de Ports] para mais informações. [[startup]] == Inicialização do Sistema Muitas distribuições Linux(R) usam o sistema init do SysV, enquanto o FreeBSD usa o tradicional man:init[8] estilo BSD. Por utilizar este sistema man:init[8], não existe níveis diferenciados de execução e o arquivo [.filename]#/etc/inittab# não existe. Ao invés disto, a inicialização é controlada por meio de scripts man:rc[8]. Na inicialização do sistema, o [.filename]#/etc/rc# lê o arquivo [.filename]#/etc/rc.conf# e o arquivo [.filename]#/etc/defaults/rc.conf# para determinar quais são os serviços que devem ser inicializados. Os serviços especificados são inicializados pela execução de scripts de inicialização localizados em [.filename]#/etc/rc.d/# e [.filename]#/usr/local/etc/rc.d/#. Esses scripts são similares aos contidos no diretório [.filename]#/etc/init.d/# dos sistemas Linux(R). Os scripts encontrados no diretório [.filename]#/etc/rc.d/# fazem parte das aplicações da "base" do sistema, tais como man:cron[8], man:sshd[8], e man:syslog[3]. Os scripts encontrados no diterório [.filename]#/usr/local/etc/rc.d/# correspondem aos aplicativos instalados pelo usuário, como por exemplo: Apache e Squid. Uma vez que o FreeBSD é desenvolvido como um sistema completo, aplicações instaladas pelos usuários não são consideradas parte do sistema "base". As aplicações dos usuários são geralmente instaladas por meio link:{handbook}#ports-using[dos Pacotes Binários ou da Coleção de Ports]. Para mantê-los separados da base do sistema, eles são instalados sob o diretório [.filename]#/usr/local/#. Portanto, os aplicativos binários instalados pelos usuários localizam-se em [.filename]#/usr/local/bin/#, e os arquivos de configuração em [.filename]#/usr/local/etc/#. Os serviços são habilitados pela adição de uma entrada no arquivo [.filename]#/etc/rc.conf# . As configurações padrões são encontradas no arquivo [.filename]#/etc/defaults/rc.conf# e essas configurações padrões são sobre postas pelas configurações realizadas no arquivo [.filename]#/etc/rc.conf#. Veja o manual do man:rc.conf[5] para maiores informações sobre as entradas disponíveis. Quando você instalar aplicações adicionais, leia as mensagens de instalação da aplicação para determinar como habilitar os serviços associados a essa aplicação. As seguintes entradas no arquivo [.filename]#/etc/rc.conf# habilitam o man:sshd[8], o Apache 2.4, e especifica que o Apache deve ser inicializado com SSL ativado. [.programlisting] .... # enable SSHD sshd_enable="YES" # enable Apache with SSL apache24_enable="YES" apache24_flags="-DSSL" .... Uma vez que o serviço tenha sido habilitado no arquivo [.filename]#/etc/rc.conf#, ele pode ser inicializado sem a necessidade de uma reinicialização do sistema. [source,shell] .... # service sshd start # service apache24 start .... Se o serviço não tiver sido habilitado, ele poderá ser inicializado a partir da linha de comando usando a opção `onestart`: [source,shell] .... # service sshd onestart .... [[network]] == Configuração de Rede Diferente da identificação genérica _ethX_ usada pelo Linux(R) para identificar a interface de rede, o FreeBSD usa o nome do driver seguido por um número. A seguinte saída do comando man:ifconfig[8] mostra duas interfaces de rede Intel(R) Pro 1000 ([.filename]#em0# e [.filename]#em1#): [source,shell] .... % ifconfig em0: flags=8843 mtu 1500 options=b inet 10.10.10.100 netmask 0xffffff00 broadcast 10.10.10.255 ether 00:50:56:a7:70:b2 media: Ethernet autoselect (1000baseTX ) status: active em1: flags=8843 mtu 1500 options=b inet 192.168.10.222 netmask 0xffffff00 broadcast 192.168.10.255 ether 00:50:56:a7:03:2b media: Ethernet autoselect (1000baseTX ) status: active .... Um endereço IP pode ser designado à uma interface utilizando o comando man:ifconfig[8]. Para torna-lo definitivo e persistente entre as reinicializações, o endereço IP deve ser incluído no arquivo [.filename]#/etc/rc.conf#. A seguinte entrada no arquivo [.filename]#/etc/rc.conf# especifica o nome da máquina, o endereço IP e o gateway padrão da rede: [.programlisting] .... hostname="server1.example.com" ifconfig_em0="inet 10.10.10.100 netmask 255.255.255.0" defaultrouter="10.10.10.1" .... Use a seguinte entrada para configurar uma interface para obter sua configuração por meio do DHCP: [.programlisting] .... hostname="server1.example.com" ifconfig_em0="DHCP" .... [[firewall]] == Firewall O sistema FreeBSD não utiliza o Linux(R) IPTABLES como seu firewall, o FreeBSD oferece três tipos de firewall a nível de kernel: * link:{handbook}#firewalls-pf[PF] * link:{handbook}#firewalls-ipf[IPFILTER] * link:{handbook}#firewalls-ipfw[IPFW] O PF é desenvolvido pelo projeto OpenBSD e portado para o FreeBSD. O PF foi criado para substituir o IPFILTER e sua sintaxe é similar ao IPFILTER. O PF pode ser utilizado em conjunto com man:altq[4] para prover funcionalidade de QoS. O exemplo abaixo mostra uma regra do PF para permitir conexões de entrada do SSH: [.programlisting] .... pass in on $ext_if inet proto tcp from any to ($ext_if) port 22 .... O IPFILTER é uma aplicação de firewall desenvolvida por Darren Reed. Ela não é específica para o FreeBSD e foi portado para diversos sistemas operacionais, incluindo NetBSD, OpenBSD, SunOS, HP/UX, e Solaris. A sintaxe do IPFILTER para permitir conexões de entrada do SSH é: [.programlisting] .... pass in on $ext_if proto tcp from any to any port = 22 .... O IPFW é o firewall desenvolvido e mantido pelo FreeBSD. Ele pode ser utilizado em conjunto com o man:dummynet[4] para prover a funcionalidade de traffic shaping e simular diferentes tipos de conexões de rede. A sintaxe do IPFW para permitir conexões de entrada do SSH é: [.programlisting] .... ipfw add allow tcp from any to me 22 in via $ext_if .... [[updates]] == Atualizando o FreeBSD Existem dois métodos para realizar a atualização em um sistema FreeBSD: a partir do código fonte ou atualização binária. Atualizar através do código fonte é a forma mais trabalhosa, mas ela oferece uma grande flexibilidade. O processo envolve a sincronização da cópia local do código fonte do FreeBSD com os servidores de Subversion do FreeBSD. Uma vez que o código fonte local esteja atualizado, uma nova versão do kernel e da userland poderão ser compiladas. Atualização binária é similar ao uso do comando `yum` ou `apt-get` para atualizar um sistema Linux(R). No FreeBSD, o comando man:freebsd-update[8] pode ser utilizado para buscar uma nova atualização binária e a instalá-la. Estas atualizações podem ser agendada usando o man:cron[8]. [NOTE] ==== Quando utilizar o man:cron[8] para agendar as atualizações, use o comando `freebsd-update cron` no arquivo man:crontab[1] para reduzir a possibilidade de que um grande número de máquinas busquem a atualização ao mesmo tempo: [.programlisting] .... 0 3 * * * root /usr/sbin/freebsd-update cron .... ==== Para maiores informações sobre a atualização por meio do código fonte ou dos updates binários, acesse o link:{handbook}#updating-upgrading[capítulo sobre atualização] do Handbook do FreeBSD. [[procfs]] == procfs: É passado, mas foi não esquecido Em algumas distribuições do Linux(R), você pode consultar o [.filename]#/proc/sys/net/ipv4/ip_forward# para verificar se o encaminhamento de IP está ou não abilitado. No FreeBSD, o comando man:sysctl[8] é utilizado para ver o status desta e também de outras variáveis do sistema. Por exemplo, use o seguinte comando para determinar se o encaminhamento de IP está ou não habilitado. [source,shell] .... % sysctl net.inet.ip.forwarding net.inet.ip.forwarding: 0 .... Use a opção `-a` para ver todas as variáveis do sistema: [source,shell] .... % sysctl -a | more .... Se alguma aplicação necessitar do procfs, adicione a seguinte entrada no arquivo [.filename]#/etc/fstab#: [source,shell] .... proc /proc procfs rw,noauto 0 0 .... Incluindo a opção `noauto` irá previnir que o [.filename]#/proc# seja montado automaticamente durante a inicialização do sistema. Para montar o sistema de arquivos sem reinicializar: [source,shell] .... # mount /proc .... [[commands]] == Comandos Comuns Alguns comandos comuns e equivalentes são os seguintes: [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Comandos do Linux (Red Hat/Debian) | Equivalente no FreeBSD | Propósito |`yum install _package_` / `apt-get install _package_` |`pkg install _package_` |Instalação de um pacote binário de um repositório remoto |`rpm -ivh _package_` / `dpkg -i _package_` |`pkg add _package_` |Instalação de um pacote local. |`rpm -qa` / `dpkg -l` |`pkg info` |Listar os pacotes instalados (Pacotes binários e através da árvore de ports) |`lspci` |`pciconf` |Lista os dispositivos PCI |`lsmod` |`kldstat` |Lista os módulos do kernel que foram carregados |`modprobe` |`kldload` / `kldunload` |Carrega/Descarrega módulos do kernel. |`strace` |`truss` |Rastreia chamadas do sistema |=== [[conclusion]] == Conclusão EEste documento forneceu uma visão geral do FreeBSD. Veja o link:{handbook}[Handbook do FreeBSD] para uma cobertura mais profunda desses tópicos, assim como outros não cobertos por este documento. diff --git a/documentation/content/pt-br/articles/mailing-list-faq/_index.adoc b/documentation/content/pt-br/articles/mailing-list-faq/_index.adoc index 9afc8f3a37..9403082d08 100644 --- a/documentation/content/pt-br/articles/mailing-list-faq/_index.adoc +++ b/documentation/content/pt-br/articles/mailing-list-faq/_index.adoc @@ -1,164 +1,174 @@ --- title: Perguntas Frequentes Sobre as Listas de Discussão do FreeBSD authors: - author: Projeto de Documentação do FreeBSD copyright: 2004-2005 Projeto de Documentação do FreeBSD releaseinfo: "$FreeBSD$" trademarks: [] --- = Perguntas Frequentes Sobre as Listas de Discussão do FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Esta é a FAQ para as listas de discussão do FreeBSD. Se você está interessado em ajudar este projeto, envie um email para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc[lista de discussão do projeto de documentação do FreeBSD]. A última versão deste documento está sempre disponível no link:.[Servidor Web do Projeto FreeBSD]. Ele também poderá ser obtido como um grande e único arquivo link:.[HTML] por meio de HTTP ou como texto puro, PostScript, PDF, etc. a partir do https://download.freebsd.org/ftp/doc/[Servidor FTP do FreeBSD]. Você também poderá querer https://www.FreeBSD.org/search/[Pesquisar na FAQ]. ''' toc::[] [[introduction]] == Introdução Como é comum com as FAQs, este documento objetiva cobrir as perguntas feitas com mais frequência a respeito das listas de discussão do FreeBSD (e claro responde-las!). Embora originalmente intencionada a reduzir o tráfego e evitar que as mesmas velhas perguntas fossem enviadas várias e várias vezes, as FAQs se tornaram reconhecidamente uma fonte de informações valiosas. Este documento tenta representar um consenso da comunidade, e como tal nunca poderá realmente ser __oficial__. Entretanto, se você encontrar erros técnicos neste documento, ou se tiver sugestões sobre itens que devam ser adicionados, por favor submeta um PR, ou envie um email para a http://lists.FreeBSD.org/mailman/listinfo/freebsd-doc[lista de discussão de documentação do projeto FreeBSD]. Obrigado. === Qual é o propósito das listas de discussão do FreeBSD? As listas de discussão do FreeBSD servem como um canal primário de comunicação para a comunidade FreeBSD, cobrindo muitos tópicos diferentes e áreas de interesse da comunidade. === Quem é o publico das listas de discussão do FreeBSD? Isto depende da premissa de cada lista. Algumas listas são mais orientadas a desenvolvedores; outras para a comunidade FreeBSD como um todo. Por favor veja http://lists.FreeBSD.org/mailman/listinfo[esta lista] para o resumo atual. === As listas de discussão do FreeBSD são abertas para a participação de qualquer pessoa? Novamente, isto dependerá das regras de cada lista. Por favor leia o objetivo da lista antes de postar, e respeite estes objetivos quando você postar. Isto ajudará a todos os participantes a terem uma experiência melhor com as listas. Se após ler as listas acima você ainda não souber para qual delas enviar a sua pergunta, provavelmente você deverá postar na lista freebsd-questions (mas antes, veja abaixo). Note também que as listas de discussão tradicionalmente tem estado abertas para postagens de não assinantes. Isto foi uma escolha deliberada, para fazer com o engajamento na comunidade FreeBSD seja um processo mais simples, e para encorajar o compartilhamento aberto de ideias. Entretanto, devido ao abuso de alguns indivíduos, algumas listas possuem agora políticas em os posts de não assinantes devem ser aprovados manualmente para ter certeza de que são apropriados. === Como posso me inscrever? Você pode usar http://lists.FreeBSD.org/mailman/listinfo[a interface web do Mailman] para se inscrever em qualquer uma das listas públicas. === Como cancelo minha inscrição? Você pode usar a mesma interface acima; ou, você pode seguir as instruções no rodapé de cada mensagem enviada pela lista. Por favor não envie mensagens de cancelamento de inscrição diretamente para as listas públicas. Primeiro, você não alcançará seu objetivo, e segundo, você irritará os outros assinantes da lista, e provavelmente você será retaliado. Este é um erro clássico ao usar as listas de discussão; por favor tente evitar isso. === O histórico da listas está disponível? Sim. Os históricos das mensagens, agrupadas por tópicos de conversa, estão disponíveis http://docs.FreeBSD.org/mail/[aqui]. === As listas de discussão estão disponíveis em um formato sumarizado (digest)? Sim. Veja a http://lists.FreeBSD.org/mailman/listinfo[interface web do Mailman]. [[etiquette]] == Etiqueta em Listas de Discussão A participação em listas de discussão, assim como a participação em qualquer comunidade, requer uma base comum para comunicação. Por favor envie apenas postagens apropriadas, e siga regras comuns de etiqueta. === O que devo fazer antes de postar? Você já deu o passo mais importante ao ler este documento. Entretanto, se você é novo no FreeBSD, você primeiro precisa se familiarizar com o software, e a história social que o envolve lendo os numerosos https://www.FreeBSD.org/docs/books/[livros e artigos] que estão disponíveis. Itens de interesse particular incluem o documento link:{faq}[Perguntas Frequentes do FreeBSD (FAQ)], o link:{handbook}[Handbook do FreeBSD], e os artigos link:{freebsd-questions-article}[Como obter melhores resultados na lista de discussão FreeBSD-questions], link:{explaining-bsd}[Explicando o BSD], e link:{new-users}[Primeiros passos no FreeBSD]. É sempre considerado errado fazer uma pergunta que já foi respondida nos documentos acima. Isto não é porque os voluntários que trabalham neste projeto são pessoas particularmente más, mas depois de um certo número de vezes respondendo às mesmas perguntas repetidas vezes, a frustração começa a surgir. Isto é particularmente verdadeiro se houver uma resposta existente para uma pergunta que já está disponível. Tenha sempre em mente que quase todo o trabalho feito no FreeBSD é feito por voluntários, e que somos apenas humanos. === O que constitui uma postagem inadequada? * As mensagens devem estar de acordo com as regras da lista de discussão. * Ataques pessoais são desencorajados. Como bons net-cidadãos, devemos tentar nos manter com altos padrões de comportamento. * Spam não é permitido, nunca. As listas de discussão são administradas ativamente para banir os infratores dessa regra. === O que é considerado etiqueta apropriada ao postar nas listas de discussão? * Por favor, use quebra de linha automática em 75 caracteres, pois nem todo mundo usa clientes de email em uma interface gráfica. * Por favor, respeite o fato de que a largura de banda não é infinita. Nem todo mundo lê e-mails através de conexões de alta velocidade, então se sua postagem envolve algo como o conteúdo de um arquivo como o [.filename]#config.log# ou um extenso stack trace, por favor considere colocar essas informações em algum lugar e apenas fornecer uma URL para eles. Lembre-se, também, de que essas postagens serão arquivadas indefinidamente, de modo que postagens enormes simplesmente aumentarão o tamanho dos arquivos muito depois que o propósito deles tiver expirado. * Formate a sua mensagem para que fique legível e, POR FAVOR, NÃO GRITE !!!!! Não subestime o efeito que uma mensagem de correio mal formatada tem, e não apenas nas listas de discussão do FreeBSD. Sua mensagem de e-mail é tudo o que as pessoas veem de você e, se estiver mal formatada, mal grafada, cheia de erros ou tiver muitos pontos de exclamação, isso dará às pessoas uma má impressão de você. * Por favor, use uma linguagem humana apropriada para uma lista de discussão específica. Muitas listas de discussão que não utilizam o idioma inglês estão https://www.FreeBSD.org/community/mailinglists/[disponíveis]. + Para os que não são, nós apreciamos que muitas pessoas não falam inglês como sua primeira língua, e tentamos fazer concessões para isso. Considera-se uma forma particularmente pobre criticar falantes não nativos por erros ortográficos ou gramaticais. O FreeBSD tem um excelente histórico neste aspecto; por favor, ajude-nos a manter essa tradição. * Por favor, use um Mail User Agent (MUA) compatível com os padrões. Muitas mensagens mal formatadas vêm de http://www.lemis.com/grog/email/email.php[clientes de email ruins ou mal-configurados]. Os seguintes clientes de email são conhecidos por enviar mensagens mal formatadas sem que você saiba sobre elas: ** exmh ** Microsoft(R) Exchange ** Microsoft(R) Outlook(R) + Tente não usar MIME: muitas pessoas usam clientes de email que não se dão muito bem com MIME. * Verifique se o seu horário e fuso horário estão definidos corretamente. Isso pode parecer um pouco bobo, já que sua mensagem ainda chegará na lista, mas muitas das pessoas nestas listas recebem centenas de mensagens por dia. Eles frequentemente classificam as mensagens recebidas por assunto e por data, e se sua mensagem não vier antes da primeira resposta, eles podem assumir que eles perderam a mensagem e não se darão ao trabalho de procurar. * Muitas das informações que você precisará fornecer referem-se a saída de programas, como man:dmesg[8], ou mensagens do console, que geralmente aparecem no [.filename]#/var/log/messages#. Não tente copiar essa informação digitando-a novamente; Isso será não só um sofrimento real, mas você é provavelmente irá cometer um erro. Para enviar o conteúdo do arquivo de log, faça uma cópia do arquivo e use um editor para reduzi-lo às informações relevantes ou copie e cole na sua mensagem. Para a saída de programas como `dmesg`, redirecione a saída para um arquivo e inclua-o. Por exemplo, + [source,shell] .... % dmesg > /tmp/dmesg.out .... + Isso redireciona as informações para o arquivo [.filename]#/tmp/dmesg.out#. * Ao usar o recurso de copiar e colar, lembre-se de que algumas dessas operações manipulam incorretamente suas mensagens. Isto é particularmente preocupante ao postar conteúdo de [.filename]#Makefiles#, onde o `tab` é um caractere significativo. Este é um problema muito comum, e muito chato, com envios para o https://www.FreeBSD.org/support/[banco de dados de Relatórios de Problemas]. Arquivos [.filename]#Makefiles# com tabs alterados para espaços, ou a chata sequência de escape `=3B`, cria um grande agravamento para os committers. === Qual é a consideração de etiqueta especial ao responder a uma postagem existente nas listas de discussão? * Por favor, inclua o texto relevante da mensagem original. Reduza-a ao mínimo, mas não exagere. Ela deverá permitir que alguém que não leu a mensagem original entenda do que você está falando. + Isso é especialmente importante para postagens do tipo "sim, também vejo isso", em que a postagem inicial era de dezenas ou centenas de linhas. * Use alguma técnica para identificar qual texto veio da mensagem original e qual texto você adicionou. Uma convenção comum é prefixar com "`>`" a mensagem original. Deixando espaço em branco após o "`>`" e deixando linhas vazias entre o seu texto e o texto original, ambos tornam o resultado mais legível. * Por favor, certifique-se de que as atribuições do texto que você está citando estão corretas. As pessoas podem ficar ofendidas se você atribuir palavras a elas que elas mesmas não escreveram. * Por favor não faça `top post`. Com isso, queremos dizer que, se você estiver respondendo a uma mensagem, coloque suas respostas após o texto copiado na sua resposta. + ** R: Porque inverte o fluxo lógico da conversa. ** P: Por que a publicação superior é desaprovada? + (Obrigado Randy Bush pela piada.) [[recurring]] == Tópicos recorrentes nas listas de discussão A participação nas listas de discussão, como a participação em qualquer comunidade, requer uma base comum para comunicação. Muitas das listas de discussão pressupõem um conhecimento da história do Projeto. Em particular, há certos tópicos que parecem ocorrer regularmente aos recém-chegados à comunidade. É da responsabilidade de cada usuário garantir que suas mensagens não se enquadrem em uma dessas categorias. Ao fazer isso, você ajudará as listas de discussão a permanecerem no tópico e, provavelmente, e provavelmente se salve de ser queimado no processo. O melhor método para evitar isso é familiarizar-se com os http://docs.FreeBSD.org/mail/[arquivos da lista de discussão], para ajudar você a entender o histórico do que aconteceu antes. E para isso, a https://www.FreeBSD.org/search/#mailinglists[interface de pesquisa das listas de discussões ] é inestimável. (Se esse método não produzir resultados úteis, por favor, complemente-o com uma pesquisa no seu mecanismo de busca favorito). Ao se familiarizar com os arquivos, você não apenas aprenderá os tópicos que foram discutidos anteriormente, mas também como a discussão tende a prosseguir nessa lista, quem são os participantes e quem é o público-alvo. Estas são sempre boas coisas para saber antes de postar em qualquer lista de discussão, não apenas em uma lista de discussão do FreeBSD. Não há dúvida de que os arquivos são bastante extensos e algumas questões recorrem com maior frequência do que outras, às vezes como acompanhamentos em que a linha de assunto não reflete mais precisamente o novo conteúdo. No entanto, o fardo está em você, o usuário, para fazer sua lição de casa para ajudar a evitar esses tópicos recorrentes. [[bikeshed]] == O que é um "Bikeshed" (Garagem de bicicletas)? Literalmente, uma `Bikeshed` é um pequeno abrigo ao ar livre no qual se pode armazenar o meio de transporte de duas rodas. No entanto, no jargão do FreeBSD, o termo refere-se a tópicos que são simples o suficiente para que (quase) qualquer um possa opinar sobre ele, e geralmente (quase) todos o fazem. A gênese desse termo é explicada com mais detalhes link:{faq}#bikeshed-painting[neste documento]. Você simplesmente deve ter um conhecimento prático deste conceito antes de postar em qualquer lista de discussão do FreeBSD. Mais genericamente, um Bikeshed é um tópico que tenderá a gerar Meta-discussões imediatas e interações hostis com usuários você ainda nem conhece. Por favor, ajude-nos a manter as listas de discussão úteis para o maior numero possível de pessoas evitando Bikesheds sempre que puder. Obrigado. [[acknowledgments]] == Agradecimentos Greg Lehey mailto:grog@FreeBSD.org[grog@FreeBSD.org]:: Autor original da maior parte do material sobre etiqueta nas listas de discussão, retirada do artigo sobre link:{freebsd-questions-article}[Como para obter os melhores resultados da lista de discussão FreeBSD-questions]. Mark Linimon mailto:linimon@FreeBSD.org[linimon@FreeBSD.org]:: Pela criação do rascunho deste FAQ. diff --git a/documentation/content/pt-br/articles/port-mentor-guidelines/_index.adoc b/documentation/content/pt-br/articles/port-mentor-guidelines/_index.adoc index 43747a133b..b8856b1460 100644 --- a/documentation/content/pt-br/articles/port-mentor-guidelines/_index.adoc +++ b/documentation/content/pt-br/articles/port-mentor-guidelines/_index.adoc @@ -1,104 +1,114 @@ --- title: Instruções para Mentores do Ports organizations: - organization: A Equipe de Gerenciamento do Ports do FreeBSD copyright: 2011 Thomas Abthorpe, Chris Rees releaseinfo: "$FreeBSD$" --- = Instruções para Mentores do Ports :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] ''' toc::[] [[port-mentor.guidelines]] == Diretrizes para relacionamentos Mentor (Orientador) / Mentee (Aprendiz) Esta seção destina-se a ajudar a desmistificar o processo de orientação (mentoria), bem como a promover abertamente uma discussão construtiva para adaptar e desenvolver as diretrizes. Em nossas vidas, temos muitas regras; nós não somos uma organização governamental que inflige regulamentação, mas sim um coletivo de indivíduos com o mesmo pensamento que trabalha em direção a um objetivo comum, mantendo a garantia de qualidade do produto que chamamos de Coleção de Ports. [[why.mentor]] === Por que tornar um Mentor? * Para a maioria de nós, fomos orientados (mentorados) quando entramos no projeto, então devolva o favor oferecendo-se para orientar (mentorar) outra pessoa. * Você tem um desejo irresistível de infligir conhecimento aos outros. * A punição usual se aplica porque você está doente e cansado de fazer o commit do bom trabalho de outra pessoa! [[mentor.comentor]] === Mentor/Co-Mentor Razões para uma co-orientação (co-mentorship): * Diferença significativa de fuso horário. Mentores acessíveis e interativos disponíveis via IM são extremamente úteis! * Barreira de idioma potencial. Sim, o FreeBSD é muito orientado para o inglês, assim como ocorre no restante da área de desenvolvimento de software, no entanto, ter um mentor que fale uma língua nativa pode ser muito útil. * ENOTIME! Até que haja um dia de 30 horas e uma semana de 8 dias, alguns de nós não tem muito tempo para dar. Compartilhar a carga com outra pessoa tornará isso mais fácil. * Um mentor iniciante pode se beneficiar da experiência de um committer/mentor mais sênior. * Duas cabeças são melhores que uma. Razões para uma mentoria solitária: * Você não joga bem com os outros. * Você prefere ter um relacionamento um-a-um. * As razões para a co-mentoria não se aplicam a você. [[mentor.expectations]] === Expectativas Esperamos que os mentores revisem e testem todos os patches propostos, pelo menos por um período inicial que dure mais de uma ou duas semanas. Esperamos que os mentores assumam a responsabilidade pelas ações de seus mentees. Um mentor deve acompanhar todos os commits que o mentee faz, tanto os aprovados quanto os implícitos. Esperamos que os mentores se certifiquem de que seus mentees leiam o link:{porters-handbook}[Porter's Handbook], o link:{pr-guidelines}[Diretrizes para manuseio de relatórios de problemas], e o link:{committers-guide}[Guia do Committer].Embora não seja necessário memorizar todos os detalhes, todo committer precisa ter uma visão geral dessas coisas para ser uma parte efetiva da comunidade (e evitar o maior número possível de erros de novato). [[mentees]] === Selecionando um Mentee Não há uma regra definida para o que torna um candidato pronto; pode ser uma combinação do número de PRs que eles enviaram, o número de ports mantidos, a frequência de atualizações dos ports e/ou o nível de participação em uma área específica de interesse como GNOME,KDE,Gecko ou outros. Um candidato deve ter quase nenhum timeout, ser responsivo a solicitações e geralmente cooperativo no suporte aos seus ports. Deve haver um histórico de comprometimento, pois é amplamente entendido que o treinamento de um committer requer tempo e esforço. Se alguém contribui já há algum tempo e já passou algum tempo observando como as coisas são feitas, podemos antecipar que existe algum conhecimento acumulado. Frequentemente vemos mantenedores que enviaram alguns PRs aparecerem no IRC perguntando quando eles receberão o commit bit. Estar inscrito e seguir as listas de discussão é muito benéfico. Não há expectativa real de que enviar postagens para as listas torne alguém um committer, mas isso demonstra comprometimento. Alguns e-mails oferecem insights sobre o conhecimento de um candidato e também como eles interagem com as outras pessoas. Da mesma forma, participar do IRC pode dar a alguém um perfil mais elevado. Pergunte a seis commiters diferentes quantos PRs um mantenedor deve enviar antes de ser indicado, e você terá seis respostas diferentes. Pergunte às mesmas pessoas por quanto tempo alguém deveria estar participando, o mesmo dilema. Quantos ports eles devem ter no mínimo? Agora nós temos um bikeshed! Algumas coisas são difíceis de quantificar, um mentor terá apenas que usar seu melhor julgamento e esperar que o portmgr concorde. [[mentorship.duration]] === Duração do Mentorship (Orientação) À medida que o nível de confiança se desenvolve e cresce, o mentee pode receber direitos "implícitos" de commit. Isso pode incluir mudanças triviais em um [.filename]#Makefile#, [.filename]#pkg-descr#, etc. Da mesma forma, pode incluir atualizações de `PORTVERSION` que não incluam alterações de `plist`. Outras circunstâncias podem ser formuladas a critério do Mentor. No entanto, durante o período de orientação, qualquer atualização de versão em um port que afete outros ports dependentes deverá ser verificada por um mentor. Assim como somos todos indivíduos diferentes, cada mentee tem uma curva de aprendizado diferente, o tempo de dedicação ao projeto e outros fatores de influência irão contribuir para o tempo necessário antes que eles possam "voar sozinhos". Empiricamente, um mentee deve ser observado por pelo menos 3 meses. O numero de 90-100 commits é um outro objetivo que um mentor poderia usar antes de liberar um mentee. Outros fatores a considerar antes de liberar um aprendiz são o número de erros que eles podem ter cometido, QATs recebidos, etc. Se eles ainda estão cometendo erros, eles ainda precisam da orientação do mentor. [[mentor.comentor.debate]] === Debate Mentor/Co-Mentor Quando um pedido chega para o portmgr, ele geralmente vem como," eu proponho 'foo' para um port commit bit, eu serei o co-mentor com 'bar'". Proposta recebida, votada e executada. O mentor é o principal ponto de contato ou o "primeiro entre os iguais", o co-mentor é o backup. Alguns reprovados, cujo nome será retido, fizeram o registro do https://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html[primeiro commit de um co-mentor]. Commits similares de co-mentors também foram vistos na árvore src. Será que isso o torna correto? Será que isto o torna errado? Parece fazer parte da evolução de como as coisas são feitas. [[mentee.expectations]] === Expectativas Esperamos que os mentees estejam preparados para críticas construtivas da comunidade. Ainda há muito "conhecimento" que não está escrito. Responder bem à uma crítica construtiva é o que esperamos que estar selecionando, ao primeiro analisar as suas contribuições existentes no IRC e nas listas de discussão. Alertamos os mentees que algumas das críticas que eles receberão podem ser menos "construtivas" do que outras, (seja através de problemas de comunicação de linguagem, ou da procura excessiva por erros pequenos ou sem importância), e que lidar com isso com tranquilidade é apenas parte de estar em uma grande comunidade. Em caso de problemas específicos com pessoas específicas, ou quaisquer dúvidas, esperamos que eles abordem um membro do portmgr no IRC ou por e-mail. diff --git a/documentation/content/pt-br/articles/pr-guidelines/_index.adoc b/documentation/content/pt-br/articles/pr-guidelines/_index.adoc index 77a4e00e5f..d257423ad3 100644 --- a/documentation/content/pt-br/articles/pr-guidelines/_index.adoc +++ b/documentation/content/pt-br/articles/pr-guidelines/_index.adoc @@ -1,478 +1,488 @@ --- title: Diretrizes para manuseio de relatórios de problemas authors: - author: Dag-Erling Smørgrav - author: Hiten Pandya releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Diretrizes para manuseio de relatórios de problemas :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Estas diretrizes descrevem as práticas de manuseio recomendadas para os Relatórios de Problemas do FreeBSD (PRs). Embora desenvolvido para a equipe de manutenção de banco de dados do FreeBSD PR mailto:freebsd-bugbusters@FreeBSD.org[freebsd-bugbusters@FreeBSD.org], essas diretrizes devem ser seguidas por qualquer pessoa que trabalhe com os Relatórios de Problemas do FreeBSD. ''' toc::[] [[intro]] == Introdução O Bugzilla é um sistema de gerenciamento de problemas usado pelo Projeto FreeBSD. Como o rastreamento preciso de defeitos de software pendentes é importante para a qualidade do FreeBSD, o uso correto do software é essencial para o avanço do projeto. O acesso ao Bugzilla está disponível para toda a comunidade do FreeBSD. Para manter a consistência dentro do banco de dados e fornecer uma experiência de usuário consistente, diretrizes foram estabelecidas cobrindo aspectos comuns do gerenciamento de erros, como apresentação de acompanhamento, tratamento de solicitações de fechamento e assim por diante. [[pr-lifecycle]] == Ciclo de vida de um relatório de problemas * O usuário envia um relatório de bug no site. O bug está no estado `Needs Triage`. * Jane Random BugBuster confirma que o relatório de erros tem informação suficiente para ser reproduzível. Se não, ela irá interagir repetidamente com o usuário para obter as informações necessárias. Neste ponto, o bug é definido para o estado `Open`. * Joe Random Committer se interessa pelo PR e o atribui a si mesmo, ou Jane Random BugBuster decide que Joe é a pessoa mais adequada para lidar com o problema e atribui o bug a ele. O bug deve ser definido para o estado `In Discussion`. * Joe tem uma breve troca com o usuário que originou o relatório de problema (certificando-se de que toda a comunicação ficou registrada na trilha de auditoria) e determina a causa do problema. * Joe vira a noite trabalhando e produz um patch que ele acha que corrige o problema, e o envia em um follow-up para o originador, pedindo que ele teste a solução. Em seguida, ele configura o estado do PR para `Patch Ready`. * Algumas iterações depois, Joe e o originador estão satisfeitos com o patch, e Joe faz o commit para o branch `-CURRENT` (ou diretamente para o branch `-STABLE` se o problema não existir no `-CURRENT`), certificando-se de fazer referencia ao Relatório de Problemas no seu log de commit (e dando o crédito ao originador caso ele tenha enviado o patch todo ou parte dele) e, se apropriado, iniciará uma contagem regressiva de MFC. O bug é então alterado para o estado `Needs MFC`. * Se o patch não precisar de passar por um MFC, Joe então fecha o PR com o status `Issue Resolved`. [NOTE] ==== Muitos PRs são submetidos contendo muito pouca informação sobre o problema, e alguns são muito complexos para resolver, ou apenas arranham a superfície de um problema maior; Nestes casos, é muito importante obter todas as informações necessárias para resolver o problema. Se o problema reportado não puder ser resolvido ou caso ele ocorra novamente, é necessário reabrir o PR. ==== [[pr-states]] == Estado do relatório de problemas É importante atualizar o status de um PR quando determinadas ações são tomadas. O status deve refletir com precisão o estado atual do trabalho no PR. .Um pequeno exemplo sobre quando alterar o estado de PR [example] ==== Quando um PR tiver sido tratado e o desenvolvedor responsável se sente confortável com a correção, ele enviará um follow up para o PR e mudará o seu estado para "feedback". Neste ponto, o originador deve avaliar a correção em seu contexto e responder indicando se o defeito foi de fato remediado. ==== Um Relatório de Problemas pode estar em um dos seguintes estados: [.glosslist] open:: Estado inicial; o problema foi apontado e precisa ser revisto. analyzed:: O problema foi revisto e uma solução está sendo procurada. feedback:: Trabalhos adicionais requerem informações adicionais do originador ou da comunidade; possivelmente informações sobre a solução proposta. patched:: Foi realizado o commit de um patch, mas algo (MFC, ou talvez confirmação do originador) ainda está pendente. suspended:: O problema não está sendo trabalhado, devido à falta de informações ou recursos. Este é um excelente candidato para alguém que está procurando um projeto para assumir. Se o problema não puder ser resolvido, ele será fechado, e não suspenso. O projeto de documentação usa suspended para itens da lista de desejos que envolvem uma quantidade significativa de trabalho para a qual ninguém tem tempo no momento. closed:: Um relatório de problemas é fechado quando as alterações referentes a ele tiverem sido integradas, documentadas e testadas ou, quando a correção do problema tiver sido abandonada. [NOTE] ==== O estado "patched" está diretamente relacionado ao feedback, então você pode passar direto para o estado de "closed" se o originador não puder testar o patch, e ele tiver funcionado no seu próprio teste. ==== [[pr-types]] == Tipos de relatórios de problemas Ao lidar com relatórios de problemas, seja como um desenvolvedor que tenha acesso direto ao banco de dados de relatórios de problemas ou como colaborador que navega no banco de dados e envia followups com patches, comentários, sugestões ou solicitações de alteração, você vai encontrar vários tipos diferentes de PRs. * <> * <> * <> * <> * <> As seções a seguir descrevem para que cada tipo diferente de PRs é usado, quando um PR pertence a um desses tipos e qual tratamento cada tipo diferente recebe. [[pr-unassigned]] == PRs não atribuídos Quando os PRs chegam, eles são inicialmente atribuídos a um responsável genérico (placeholder). Estes são sempre prefixados com `freebsd-`. O valor exato para esse padrão depende da categoria; na maioria dos casos, corresponde a uma lista de discussão específica do FreeBSD. Aqui está a lista atual, com os mais comuns listados primeiro: [[default-assignees-common]] .Responsáveis ​​Padrões - mais comuns [cols="1,1,1", options="header"] |=== | Tipo | Categorias | Responsável Padrão |sistema base |bin, conf, gnu, kern, misc |freebsd-bugs |arquitetura específica |alpha, amd64, arm, i386, ia64, powerpc, sparc64 |freebsd-_arch_ |Coleção de Ports |ports |freebsd-ports-bugs |documentação enviada com o sistema |docs |freebsd-doc |Páginas web do FreeBSD (não incluindo docs) |Website |freebsd-www |=== [[default-assignees-other]] .Responsável Padrão - outros [cols="1,1,1", options="header"] |=== | Tipo | Categorias | Responsável Padrão |esforços de advocacia |advocacia |freebsd-advocacy |Problemas com Java Virtual Machine(TM) |Java |freebsd-java |conformidade com padrões |padrões |freebsd-standards |bibliotecas de threading |threads |freebsd-threads |Subsistema man:usb[4] |USB |freebsd-usb |=== Não se surpreenda ao descobrir que o usuário responsável pelo PR atribuiu a categoria errada. Se você corrigir a categoria, não se esqueça de corrigir a atribuição também. (Em particular, nossos usuários parecem ter dificuldade em entender que apenas porque seu problema se manifesta em um sistema i386, que ele pode ser genérico para todo o FreeBSD, e assim ser mais apropriado para o `kern`. O oposto também é verdade, claro.) Certos PRs podem ser reatribuídos para longe destes responsáveis genéricos por qualquer pessoa. Existem vários tipos de responsáveis: listas de discussão especializadas; aliases de correio (usados ​​para determinados itens de interesse limitado); e indivíduos. Para os responsáveis ​​que são listas de discussão, use o formulário longo ao fazer a atribuição (por exemplo, `freebsd-foo` em vez de `foo`); isso evitará emails duplicados enviados para a lista de discussão. [NOTE] ==== Como a lista de indivíduos que se voluntariaram para ser o responsável padrão para certos tipos de PRs muda com bastante frequência, ela é muito mais adequada para o https://wiki.freebsd.org/AssigningPRs[the FreeBSD wiki]. ==== Aqui está uma lista de exemplo de tais entidades; provavelmente não está completa. [[common-assignees-base]] .Responsáveis ​​Comuns - sistema base [cols="1,1,1,1", options="header"] |=== | Tipo | Categoria Sugerida | Responsável Sugerido | Tipo de Responsável |problema específico da arquitetura ARM(R) |arm |freebsd-arm |lista de discussão |problema específico da arquitetura MIPS(R) |kern |freebsd-mips |lista de discussão |problema específico da arquitetura PowerPC(R) |kern |freebsd-ppc |lista de discussão |problema com Configuração Avançada e Gerenciamento de Energia (man:acpi[4]) |kern |freebsd-acpi |lista de discussão |problema com os drivers de modo de transferência assíncrona (ATM) |kern |freebsd-atm |lista de discussão |problema com sistemas FreeBSD embarcados ou de small-footprint (por exemplo, NanoBSD/PicoBSD/FreeBSD-arm) |kern |freebsd-embedded |lista de discussão |problema com os drivers FireWire(R) |kern |freebsd-firewire |lista de discussão |problema com o código do sistema de arquivos |kern |freebsd-fs |lista de discussão |problema com o subsistema man:geom[4] |kern |freebsd-geom |lista de discussão |problema com o subsistema man:ipfw[4] |kern |freebsd-ipfw |lista de discussão |problema com os drivers de rede digital de serviços integrados (ISDN) |kern |freebsd-isdn |lista de discussão |subsistema man:jail[8] |kern |freebsd-jail |lista de discussão |problema com a emulação Linux(R) ou SVR4 |kern |freebsd-emulation |lista de discussão |problema com a pilha de rede |kern |freebsd-net |lista de discussão |problema com o subsistema man:pf[4] |kern |freebsd-pf |lista de discussão |problema com o subsistema man:scsi[4] |kern |freebsd-scsi |lista de discussão |problema com o subsistema man:sound[4] |kern |freebsd-multimedia |lista de discussão |problemas com o subsistema man:wlan[4] e drivers sem fio |kern |freebsd-wireless |lista de discussão |problema com o man:sysinstall[8] ou man:bsdinstall[8] |bin |freebsd-sysinstall |lista de discussão |problema com os scripts de inicialização do sistema (man:rc[8]) |kern |freebsd-rc |lista de discussão |problema com funcionalidade VIMAGE ou VNET e código relacionado |kern |freebsd-virtualization |lista de discussão |problema com a emulação de Xen |kern |freebsd-xen |lista de discussão |=== [[common-assignees-ports]] .Responsáveis Comuns - Ports Collection [cols="1,1,1,1", options="header"] |=== | Tipo | Categoria Sugerida | Responsável Sugerido | Tipo de Responsável |problema com o framework da coleção de ports (__não__ com um port individual!) |ports |portmgr |alias |port que é mantido por apache@FreeBSD.org |ports |apache |lista de discussão |port que é mantido por autotools@FreeBSD.org |ports |autotools |alias |port que é mantido por doceng@FreeBSD.org |ports |doceng |alias |port que é mantido por eclipse@FreeBSD.org |ports |freebsd-eclipse |lista de discussão |port que é mantido por gecko@FreeBSD.org |ports |gecko |lista de discussão |port que é mantido por gnome@FreeBSD.org |ports |gnome |lista de discussão |port que é mantido por hamradio@FreeBSD.org |ports |hamradio |alias |port que é mantido por haskell@FreeBSD.org |ports |haskell |alias |port que é mantido por java@FreeBSD.org |ports |freebsd-java |lista de discussão |port que é mantido por kde@FreeBSD.org |ports |kde |lista de discussão |port que é mantido por mono@FreeBSD.org |ports |mono |lista de discussão |port que é mantido por office@FreeBSD.org |ports |freebsd-office |lista de discussão |port que é mantido por perl@FreeBSD.org |ports |perl |lista de discussão |port que é mantido por python@FreeBSD.org |ports |freebsd-python |lista de discussão |port que é mantido por ruby@FreeBSD.org |ports |freebsd-ruby |lista de discussão |port que é mantido por secteam@FreeBSD.org |ports |secteam |alias |port que é mantido por vbox@FreeBSD.org |ports |vbox |alias |port que é mantido por x11@FreeBSD.org |ports |freebsd-x11 |lista de discussão |=== Os PRs relacionados aos ports que têm um mantenedor que é um committer de ports podem ser reatribuídas por qualquer um (mas note que nem todo committer do FreeBSD é necessariamente um committer de ports, então você não pode simplesmente ir sozinho pelo endereço de email). Para outros PRs, por favor, não os reatribua para outros indivíduos (outros que não sejam você), a menos que tenha certeza de que o responsável realmente deseja acompanhar o PR. Isso ajudará a evitar situações em que ninguém se dedica para consertar um problema em particular, porque todos assumem que o responsável já está trabalhando nele. [[common-assignees-other]] .Responsáveis ​​Comuns - Outros [cols="1,1,1,1", options="header"] |=== | Tipo | Categoria Sugerida | Responsável Sugerido | Tipo de Responsável |problema com o banco de dados de PR |bin |bugmeister |alias |problema com o https://bugs.freebsd.org/submit/[formulário web] do Bugzilla. |doc |bugmeister |alias |=== [[pr-assigned]] == PRs Atribuídos Se um PR tiver o campo `responsible` configurado para o nome de usuário de um desenvolvedor do FreeBSD, isso significa que o PR foi entregue a essa pessoa em particular para trabalho adicional. PRs designados não devem ser tocados por ninguém além do responsável ou do bugmeister. Se você tiver comentários, envie um followup. Se, por algum motivo, você achar que o PR deve mudar de estado ou ser reatribuído, envie uma mensagem ao responsável. Se o responsável não responder dentro de duas semanas, cancele a atribuição do PR e faça o que quiser. [[pr-dups]] == PRs Duplicados Se você encontrar mais de um PR que descreva o mesmo problema, escolha aquele que contém a maior quantidade de informações úteis e feche os outros, indicando claramente o número do PR substituto. Se vários PRs contiverem informações úteis que não se sobrepõem, envie todas as informações ausentes para um para um deles por meio de um followup, incluindo referências aos outros; em seguida, feche os outros PRs (que agora estão completamente substituídos). [[pr-stale]] == PRs Obsoletos Um PR é considerado obsoleto se não tiver sido modificado em mais de seis meses. Aplique o seguinte procedimento para lidar com PRs obsoletos: * Se o PR contiver detalhes suficientes, tente reproduzir o problema no `-CURRENT` e no `-STABLE`. Se você tiver sucesso, envie um followup detalhando suas descobertas e tente encontrar alguém para atribuí-lo. Defina o estado para "analyzed", se apropriado. * Se o PR descrever um problema que você sabe ser o resultado de um erro de uso (configuração incorreta ou outra coisa do tipo), envie um followup explicando o que o originador fez de errado e feche o PR com o motivo "User error" ou "Configuration error". * Se o PR descreve um erro que você sabe ter sido corrigido no `-CURRENT` e `-STABLE`, feche-o com uma mensagem informando quando ele foi corrigido em cada branch. * Se o PR descreve um erro que você sabe ter sido corrigido no `-CURRENT`, mas não no `-STABLE`, tente descobrir quando a pessoa que o corrigiu está planejando o MFC ou tente encontrar alguém (talvez você?) para fazê-lo. Defina o estado para "patched" e atribua-o a quem quer que tenha ficado responsável por fazer o MFC. * Em outros casos, peça ao originador para confirmar se o problema ainda existe em versões mais recentes. Se o originador não responder dentro de um mês, feche o PR com a notação "Feedback timeout". [[pr-misfiled-notpr]] == PRs Sem Erros Desenvolvedores que se deparem com PRs que na verdade deveriam ter sido postados na http://lists.FreeBSD.org/mailman/listinfo/freebsd-bugs[freebsd-bugs] ou em alguma outra lista deve fechar o PR, e informar o originador em um comentário do porque o problema reportado não é realmente um PR e orientá-lo sobre onde a mensagem deve ser postada. Os endereços de e-mail que o Bugzilla utiliza para receber os PRs foram publicados como parte da documentação do FreeBSD, e também foram anunciados e listados no website. Isso significa que os spammers os encontraram. Sempre que você fechar um desses PRs, faça o seguinte: * Defina o componente como `junk` (em `Supporting Services`). * Defina o responsável para `nobody@FreeBSD.org`. * Defina o estado como `Issue Resolved`. Definir a categoria como `junk` torna óbvio que não há conteúdo útil dentro do PR e ajuda a reduzir a desordem nas categorias principais. [[references]] == Leitura Adicional Esta é uma lista de recursos relevantes para a escrita e processamento adequado de um relatório de problema. De forma alguma deve ser considerada completa. * link:{problem-reports}[Como escrever relatórios de problemas para o FreeBSD] - diretrizes para usuários que enviam um PR. diff --git a/documentation/content/pt-br/articles/rc-scripting/_index.adoc b/documentation/content/pt-br/articles/rc-scripting/_index.adoc index 37dff7e0dd..0a3149a4fc 100644 --- a/documentation/content/pt-br/articles/rc-scripting/_index.adoc +++ b/documentation/content/pt-br/articles/rc-scripting/_index.adoc @@ -1,596 +1,606 @@ --- title: Scripts rc.d práticos no BSD authors: - author: Yar Tikhiy email: yar@FreeBSD.org copyright: 2005-2006, 2012 The FreeBSD Project releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "netbsd", "general"] --- = Scripts rc.d práticos no BSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Os iniciantes podem achar difícil relacionar os fatos da documentação formal do framework [.filename]#rc.d# do BSD com as tarefas práticas do script [.filename]#rc.d#. Neste artigo, consideramos alguns casos típicos de complexidade crescente, vamos mostrar os recursos do [.filename]#rc.d# adequados para cada caso e vamos discutir como eles funcionam. Esse exame deve fornecer pontos de referência para um estudo mais aprofundado do design e da aplicação eficiente do [.filename]#rc.d#. ''' toc::[] [[rcng-intro]] == Introdução Historicamente o BSD tinha um script de inicialização monolítico, o [.filename]#/etc/rc#. Ele era chamado pelo man:init[8] no momento da inicialização do sistema e executava todas as tarefas necessárias para a operação multi-usuário: verificação e montagem do sistemas de arquivos, configuração de rede, iniciava daemons e assim por diante. A lista precisa de tarefas não era a mesma em todos os sistemas; os administradores precisavam personalizá-lo. Com poucas exceções, o [.filename]#/etc/rc# teve que ser modificado, e os verdadeiros hackers gostaram disso. O problema real com a abordagem monolítica era que ela não fornecia nenhum controle sobre os componentes individuais iniciados a partir do [.filename]#/etc/rc#. Por exemplo, o [.filename]#/etc/rc# não podia reiniciar um único daemon. O administrador do sistema tinha que encontrar o processo daemon manualmente, matá-lo, esperar até que ele realmente finalizasse, então procurar pelas flags no [.filename]#/etc/rc#, e finalmente digitar a linha de comando completa para iniciar o daemon novamente. A tarefa se tornaria ainda mais difícil e propensa a erros se o serviço de reinicialização consistisse em mais de um daemon ou exigisse ações adicionais. Em poucas palavras, o único script não cumpriu o objetivo dos scripts: tornar a vida do administrador do sistema mais fácil. Mais tarde, houve uma tentativa de dividir algumas partes do [.filename]#/etc/rc# para iniciar os subsistemas mais importantes separadamente. O exemplo notório foi o [.filename]#/etc/netstart# para configurar a rede. Ele permitia acessar a rede a partir do modo single-user, mas não se integrou bem ao processo de inicialização automática porque partes de seu código precisavam intercalar com ações essencialmente não relacionadas à rede. Foi por isso que o [.filename]#/etc/netstart# mudou para [.filename]#/etc/rc.network#. Este último não era mais um script comum; ele era composto por um emaranhado de funções man:sh[1] chamadas pelo [.filename]#/etc/rc# em diferentes estágios da inicialização do sistema. No entanto, a medida que as tarefas de inicialização cresciam variadas e sofisticadas, a abordagem "quase modular" tornou-se ainda mais engessada do que o monolítico [.filename]#/etc/rc#. Sem um framework limpo e bem projetado, os scripts de inicialização tiveram que se curvar para satisfazer as necessidades de desenvolvimento rápido dos sistemas operacionais baseados no BSD. Tornou-se óbvio, finalmente, que mais passos eram necessários no caminho para construção de um sistema [.filename]#rc# extensível e customizável. Assim nasceu o BSD [.filename]#rc.d#. Seus pais reconhecidos foram o Luke Mewburn e a comunidade do NetBSD. Mais tarde ele foi importado para o FreeBSD. Seu nome se refere à localização dos scripts do sistema para serviços individuais, que é o [.filename]#/etc/rc.d#. Em breve, vamos aprender sobre mais componentes do sistema [.filename]#rc.d# e vamos ver como os scripts individuais são invocados. As idéias básicas por trás do BSD [.filename]#rc.d# são _modularidade fina_ e __reutilização de código__. _Modularidade fina_ significa que cada "serviço básico", como um daemon do sistema ou uma tarefa de inicialização primitiva, obtém seu próprio script man:sh[] capaz de iniciar o serviço, pará-lo, recarregá-lo e verificar seu status. Uma ação específica é escolhida pelo argumento da linha de comando para o script. O script [.filename]#/etc/rc# ainda comanda a inicialização do sistema, mas agora ele simplesmente invoca os scripts menores um por um com o argumento `start`. É fácil executar tarefas de desligamento executando o mesmo conjunto de scripts com o argumento `stop`, o que é feito pelo [.filename]#/etc/rc.shutdown#. Observe como isso segue de perto o modo Unix de ter um conjunto de pequenas ferramentas especializadas, cada uma cumprindo sua tarefa da melhor forma possível. _Reutilização de código_ significa que operações comuns são implementadas como funções man:sh[1] e coletadas em [.filename]#/etc/rc.subr#. Agora, um script típico pode conter apenas algumas linhas de código man:sh[1]. Finalmente, uma parte importante do framework do [.filename]#rc.d# é man:rcorder[8], o qual ajuda o [.filename]#/etc/rc# a executar os pequenos scripts ordenadamente em relação às dependências entre eles. Ele também pode ajudar o [.filename]#/etc/rc.shutdown#, porque a ordem apropriada para a sequência de encerramento é oposta à da inicialização. O design do BSD [.filename]#rc.d# é descrito no <>, e os componentes do [.filename]#rc.d# são documentados em grande detalhe nas <>. No entanto, pode não parecer óbvio para um novato em [.filename]#rc.d# como amarrar os inúmeros pedaços juntos para criar um script bem estilizado para uma tarefa específica. Portanto, este artigo tentará uma abordagem diferente para descrever o [.filename]#rc.d#. Ele mostrará quais recursos devem ser usados em vários casos típicos e por quê. Note que este não é um documento explicativo porque nosso objetivo não é fornecer receitas prontas, mas mostrar algumas entradas fáceis no domínio do [.filename]#rc.d#. Nem este artigo é um substituto para as páginas de manual relevantes. Não hesite em consultá-los para obter uma documentação mais formal e completa ao ler este artigo. Existem pré-requisitos para entender este artigo. Primeiro de tudo, você deve estar familiarizado com a linguagem de script man:sh[1] para poder dominar o [.filename]#rc.d#. Além disso, você deve saber como o sistema executa as tarefas de inicialização e encerramento do userland, o que está descrito em man:rc[8]. Este artigo foca no branch [.filename]#rc.d# do FreeBSD. No entanto, ele também pode ser útil para os desenvolvedores do NetBSD, porque os dois branchs [.filename]#rc.d# do BSD não apenas compartilham o mesmo design, mas também permanecem similares em seus aspectos visíveis aos autores do script. [[rcng-task]] == Esboçando a tarefa Um pouco de consideração antes de iniciar o `$EDITOR` não irá prejudicar. Para escrever um script [.filename]#rc.d# corretamente customizado para um serviço do sistema, devemos poder responder as seguintes questões primeiro: * O serviço é obrigatório ou opcional? * O script servirá um único programa, por exemplo, um daemon, ou realizará ações mais complexas? * De quais outros serviços nosso serviço dependerá e vice-versa? A partir dos exemplos que se seguem, veremos o porque é importante conhecer as respostas a essas perguntas. [[rcng-dummy]] == Um script fictício O script a seguir apenas emite uma mensagem toda vez que o sistema é inicializado: [.programlisting] .... #!/bin/sh <.> . /etc/rc.subr <.> name="dummy" <.> start_cmd="${name}_start" <.> stop_cmd=":" <.> dummy_start() <.> { echo "Nothing started." } load_rc_config $name <.> run_rc_command "$1" <.> .... Os pontos a serem observadas são: ➊ Um script interpretado deve começar com a linha mágica "shebang". Essa linha especifica o programa interpretador para o script. Devido a linha shebang, o script pode ser invocado exatamente como um programa binário, desde que tenha o bit de execução definido. (Veja man:chmod[1].) Por exemplo, um administrador do sistema pode executar nosso script manualmente, a partir da linha de comando: [source,shell] .... # /etc/rc.d/dummy start .... [NOTE] ==== Para ser adequadamente gerenciado pelo framework do [.filename]#rc.d#, seus scripts precisam ser escritos na linguagem man:sh[1]. Se você tiver um serviço ou port que use um utilitário de controle binário ou uma rotina de inicialização escrita em outra linguagem, instale este elemento em [.filename]#/usr/sbin# (para o sistema) ou em [.filename]#/usr/local/sbin# (para um port) e invoque-o por meio de um script man:sh[1] no diretório apropriado do [.filename]#rc.d#. ==== [TIP] ==== Caso você queira aprender os detalhes do porque os scripts [.filename]#rc.d# devem ser escritos na linguagem man:sh[1], veja como o [.filename]#/etc/rc# invoca-os por meio de `run_rc_script`, e então estude a implementação de `run_rc_script` em [.filename]#/etc/rc. subr#. ==== ➋ Em [.filename]#/etc/rc.subr#, várias funções man:sh[1] estão definidas para serem utilizadas por um script [.filename]#rc.d#. As funções estão documentadas em man:rc.subr[8]. Embora seja teoricamente possível escrever um script [.filename]#rc.d# sem usar o man:rc.subr[8], as suas funções são extremamente úteis e tornam o trabalho mais fácil. Portanto, não é de surpreender que todos recorram a scripts man:rc.subr[8] em [.filename]#rc.d#. Nós não vamos ser uma exceção. Um script [.filename]#rc.d# deve "incluir" o [.filename]#/etc/rc.subr# (isto por ser feito usando o comando "`.`") _antes_ que ele chame as funções do man:rc.subr[8] para que o man:sh[1] tenha a oportunidade para aprender as funções. O estilo preferido é incluir o [.filename]#/etc/rc.subr# antes de tudo. [NOTE] ==== Algumas funções úteis relacionadas a rede são fornecidas por outro arquivo include, o [.filename]#/etc/network.subr#. ==== ➌ [[name-var]]A variável obrigatória `name` especifica o nome do nosso script. Ela é exigida pelo man:rc.subr[8]. Ou seja, cada script [.filename]#rc.d# __deve__ definir a variável `name` antes de chamar funções do man:rc.subr[8]. Agora é o momento certo para escolher um nome exclusivo para o nosso script de uma vez por todas. Vamos usá-lo em vários lugares enquanto desenvolvemos o script. Para começar, também vamos dar o mesmo nome ao arquivo de script. [NOTE] ==== O estilo atual do script [.filename]#rc.d# é incluir valores atribuídos as variáveis entre aspas duplas. Tenha em mente que é apenas um problema de estilo que nem sempre pode ser aplicável. Você pode omitir com segurança as aspas das palavras simples sem os metacaracteres do man:sh[1] nelas, enquanto em certos casos você precisará de aspas simples para evitar qualquer interpretação do valor pelo man:sh[1]. Um programador deve ser capaz de dizer a sintaxe da linguagem a partir das convenções de estilo e bem como de usá-las sabiamente. ==== ➍ A idéia principal por trás do man:rc.subr[8] é que um script [.filename]#rc.d# fornece manipuladores, ou métodos, para o man:rc.subr[8] invocar. Em particular, `start`, `stop` e outros argumentos para um script [.filename]#rc.d# são tratados desta maneira. Um método é uma expressão man:sh[1] armazenada em uma variável denominada `argument_cmd`, no qual _argument_ corresponde ao que pode ser especificado na linha de comando do script. Vamos ver mais adiante como o man:rc.subr[8] fornece métodos default para os argumentos padrão. [NOTE] ==== Para tornar o código em [.filename]#rc.d# mais uniforme, é comum usar `${name}` onde for apropriado. Assim, várias linhas podem ser copiadas de um script para outro. ==== ➎ Devemos ter em mente que o man:rc.subr[8] fornece métodos default para os argumentos padrões. Consequentemente, devemos sobrescrever um método default com uma expressão no-op man:sh[] se desejarmos que ele não faça nada. ➏ O corpo de um método sofisticado pode ser implementado como uma função. É uma boa ideia tornar o nome da função significativo. [IMPORTANT] ==== É altamente recomendado adicionar o prefixo `${name}` aos nomes de todas as funções definidas em nosso script, para que eles nunca entrem em conflito com as funções do man:rc.subr[8] ou outro arquivo de inclusão comum. ==== ➐ Essa chamada ao man:rc.subr[8] carrega as variáveis do man:rc.conf[5]. Nosso script não faz uso delas ainda, mas ainda assim é recomendado carregar o man:rc.conf[5] pois podem haver variáveis man:rc.conf[5] controlando o man:rc.subr[8] propriamente dito. ➑ Geralmente este é o último comando em um script [.filename]#rc.d#. Ele invoca o maquinário man:rc.subr[8] para executar a ação solicitada usando as variáveis e métodos que nosso script forneceu. [[rcng-confdummy]] == Um script fictício configurável Agora vamos adicionar alguns controles ao nosso script fictício. Como você deve saber, os scripts [.filename]#rc.d# são controlados pelo man:rc.conf[5]. Felizmente, o man:rc.subr[8] esconde todas as complicações de nós. O script a seguir usa o man:rc.conf[5] via man:rc.subr[8] para ver se ele está habilitado em primeiro lugar, e buscar uma mensagem para mostrar no momento da inicialização. Estas duas tarefas são de fato independentes. Por um lado, um script [.filename]#rc.d# pode apenas suportar a ativação e desativação de seu serviço. Por outro lado, um script [.filename]#rc.d# obrigatório pode ter variáveis de configuração. Nós vamos fazer as duas coisas no mesmo script: [.programlisting] .... #!/bin/sh . /etc/rc.subr name=dummy rcvar=dummy_enable <.> start_cmd="${name}_start" stop_cmd=":" load_rc_config $name <.> : ${dummy_enable:=no} <.> : ${dummy_msg="Nothing started."} <.> dummy_start() { echo "$dummy_msg" <.> } run_rc_command "$1" .... O que mudou neste exemplo? ➊ A variável `rcvar` especifica o nome da variável do botão ON/OFF. ➋ Agora o `load_rc_config` é invocado anteriormente no script, antes que qualquer variável do man:rc.conf[5] seja acessada. [NOTE] ==== Ao examinar os scripts [.filename]#rc.d#, tenha em mente que o man:sh[1] adia a avaliação de expressões em uma função até que a função seja chamada. Portanto, não é um erro invocar `load_rc_config` tão tarde quanto antes do `run_rc_comman` e ainda acessar as variáveis do man:rc.conf[5] a partir do método das funções exportadas para o `run_rc_command`. Isto ocorre porque as funções do método devem ser chamadas por `run_rc_command`, que é chamado _após_ o `load_rc_config`. ==== ➌ Um aviso será emitido pelo `run_rc_command` se o próprio `rcvar` estiver definido, mas a variável de knob indicada não estiver definida. Se o seu script [.filename]#rc.d# for para o sistema base, você deve adicionar uma configuração padrão para o knob no [.filename]#/etc/defaults/rc.conf# e documentá-lo em man:rc.conf[5]. Caso contrário, será o seu script que deverá fornecer uma configuração padrão para o knob. A abordagem canônica para o último caso é mostrada no exemplo. [NOTE] ==== Você pode fazer o man:rc.subr[8] agir como se o knob fosse definido como `ON`, independentemente da sua configuração atual, prefixando o argumento para o script com `one` ou `force`, como em `onestart` ou `forcestop`. Tenha em mente que o `force` tem outros efeitos perigosos que mencionaremos abaixo, enquanto `one` apenas sobrescreve o knob ON/OFF. Por exemplo, suponha que `dummy_enable` seja `OFF`. O comando a seguir executará o método `start` apesar da configuração: [source,shell] .... # /etc/rc.d/dummy onestart .... ==== ➍ Agora, a mensagem a ser mostrada no momento da inicialização não é mais codificada no script. Ela é especificada por uma variável do man:rc.conf[5] chamada `dummy_msg`. Este é um exemplo trivial de como as variáveis do man:rc.conf[5] podem controlar um script [.filename]#rc.d#. [IMPORTANT] ==== Os nomes de todas as variáveis do man:rc.conf[5] usadas exclusivamente pelo nosso script _devem_ possuir o mesmo prefixo: `${name}_`. Por exemplo: `dummy_mode`, `dummy_state_file`, e assim por diante. ==== [NOTE] ==== Embora seja possível usar um nome mais curto internamente, por exemplo, apenas `msg`, adicionar o prefixo exclusivo `${name}_` a todos os nomes globais introduzidos pelo nosso script nos salvará de possíveis colisões com o nome das funções existentes no man:rc.subr[8]. Como regra, os scripts [.filename]#rc.d# do sistema base não precisam fornecer valores padrões para as suas variáveis man:rc.conf[5] porque os padrões devem ser definidos em [.filename]#/etc/defaults/rc.conf#. Por outro lado, os scripts [.filename]#rc.d# para os ports devem fornecer os valores padrões, conforme mostrado no exemplo. ==== ➎ Aqui usamos `dummy_msg` para realmente controlar nosso script, ou seja, para emitir uma mensagem variável. O uso de uma função de shell é um exagero aqui, já que ele só executa um único comando; uma alternativa igualmente válida seria: [.programlisting] .... start_cmd="echo \"$dummy_msg\"" .... [[rcng-daemon]] == Inicialização e desligamento de um daemon simples Dissemos anteriormente que o man:rc.subr[8] poderia fornecer métodos padrão. Obviamente, estes padrões não podem ser muito gerais. Eles são adequados para o caso comum de iniciar e encerrar um programa daemon simples. Vamos supor agora que precisamos escrever um script [.filename]#rc.d# para um daemon chamado `mumbled`. Aqui está: [.programlisting] .... #!/bin/sh . /etc/rc.subr name=mumbled rcvar=mumbled_enable command="/usr/sbin/${name}" <.> load_rc_config $name run_rc_command "$1" .... Agradavelmente simples, não é? Vamos examinar nosso pequeno script. A única coisa nova a observar é o seguinte: ➊ A variável `command` é significativa para o man:rc.subr[8]. Se estiver definido, o man:rc.subr[8] agirá de acordo com o cenário de servir um daemon convencional. Em particular, os métodos padrão serão fornecidos para tais argumentos: `start`, `stop`, `restart`, `poll`, e `status`. O daemon será iniciado executando `$command` com os sinalizadores de linha de comando especificados por `$mumbled_flags`. Assim, todos os dados de entrada para o método padrão `start` estão disponíveis nas variáveis configuradas pelo nosso script. Ao contrário do `start`, outros métodos podem requerer informações adicionais sobre o processo iniciado. Por exemplo, `stop` deve conhecer o PID do processo para terminá-lo. No presente caso, man:rc.subr[8]varrerá a lista de todos os processos, procurando por um processo com seu nome igual a `$procname`. Esta última é outra variável de significado para man:rc.subr[8], e seu valor é padronizado para `command`. Em outras palavras, quando definimos o `command`, `procname` é efetivamente definido para o mesmo valor. Isso permite que nosso script mate o daemon e verifique se ele está sendo executado em primeiro lugar. [NOTE] ==== Alguns programas são, na verdade, scripts executáveis. O sistema executa esse script iniciando seu interpretador e passando o nome do script para ele como um argumento de linha de comando. Isso é refletido na lista de processos, que podem confundir o man:rc.subr[8]. Você também deve definir o `command_interpreter` para permitir que o man:rc.subr[8] saiba o nome real do processo se o `$command` é um script. Para cada script [.filename]#rc.d#, existe uma variável man:rc.conf[] que tem precedência sobre `command`. Seu nome é construído da seguinte forma: `${name}_program`, onde `name` é a variável obrigatória que discutimos <>. Por exemplo, neste caso, será `mumbled_program`. É man:rc.subr[8] que organiza `${name}_program` para substituir o comando. Obviamente, o man:sh[1] permitirá que você defina `${name}_program` a partir do man:rc.conf[5] ou o próprio script, mesmo que o `command` esteja indefinido. Nesse caso, as propriedades especiais de `${name}_program` são perdidas e se tornam uma variável comum que seu script pode usar para seus próprios propósitos. No entanto, o uso exclusivo de `${name}_program` é desencorajado porque usá-lo junto com o `command` tornou-se um idioma na escrita de scripts [.filename]#rc.d#. ==== Para obter informações mais detalhadas sobre métodos padrões, consulte man:rc.subr[8]. [[rcng-daemon-adv]] == Inicialização e desligamento de um daemon avançado Vamos adicionar um pouco de carne aos ossos do script anterior e torná-lo mais complexo e cheio de funcionalidades. Os métodos padrões podem fazer um bom trabalho para nós, mas podemos precisar ajustar alguns dos seus aspectos. Agora vamos aprender como ajustar os métodos padrões para as nossas necessidades. [.programlisting] .... #!/bin/sh . /etc/rc.subr name=mumbled rcvar=mumbled_enable command="/usr/sbin/${name}" command_args="mock arguments > /dev/null 2>&1" <.> pidfile="/var/run/${name}.pid" <.> required_files="/etc/${name}.conf /usr/shared/misc/${name}.rules" <.> sig_reload="USR1" <.> start_precmd="${name}_prestart" <.> stop_postcmd="echo Bye-bye" <.> extra_commands="reload plugh xyzzy" <.> plugh_cmd="mumbled_plugh" <.> xyzzy_cmd="echo 'Nothing happens.'" mumbled_prestart() { if checkyesno mumbled_smart; then <.> rc_flags="-o smart ${rc_flags}" <.> fi case "$mumbled_mode" in foo) rc_flags="-frotz ${rc_flags}" ;; bar) rc_flags="-baz ${rc_flags}" ;; *) warn "Invalid value for mumbled_mode" <.> return 1 <.> ;; esac run_rc_command xyzzy <.> return 0 } mumbled_plugh() <.> { echo 'A hollow voice says "plugh".' } load_rc_config $name run_rc_command "$1" .... ➊ Argumentos adicionais para `$command` podem ser passados em `command_args`. Eles serão adicionados a linha de comando após `$mumbled_flags`. Como a linha de comando final é passada para `eval` para sua execução real, os redirecionamentos de entrada e saída podem ser especificados em `command_args`. [NOTE] ==== _Nunca_ inclua opções tracejadas, como `-X` ou `--foo`, em `command_args`. O conteúdo de `command_args` aparecerá no final da linha de comando final, portanto é provável que eles sigam os argumentos presentes em `${name}_flags`; mas a maioria dos comandos não reconhecerá opções tracejadas após argumentos comuns. Uma maneira melhor de passar opções adicionais para `$command` é adicioná-las ao início de `${name}_flags`. Outra maneira é modificar `rc_flags` <>. ==== ➋ Um daemon de boas maneiras deve criar um _pidfile_ para que seu processo possa ser encontrado com mais facilidade e confiabilidade. A variável `pidfile`, se configurada, informa ao man:rc.subr[8] onde pode encontrar o pidfile para seus métodos padrão possam usar. [NOTE] ==== De fato, o man:rc.subr[8] também usará o pidfile para ver se o daemon já está em execução antes de iniciá-lo. Esta verificação pode ser ignorada usando o argumento `faststart`. ==== ➌ Se o daemon não puder ser executado a menos que existam certos arquivos, apenas liste-os em `required_files`, e man:rc.subr[8] irá verificar se esses arquivos existem antes de iniciar o daemon. Também existem `required_dirs` e `required_vars` para diretórios e variáveis de ambiente, respectivamente. Todos eles são descritos em detalhes em man:rc.subr[8]. [NOTE] ==== O método padrão de man:rc.subr[8] pode ser forçado a ignorar as verificações de pré-requisitos usando `forcestart` como o argumento para o script. ==== ➍ Podemos personalizar sinais para enviar para o daemon caso eles sejam diferentes dos mais conhecidos. Em particular, `sig_reload` especifica o sinal que faz o daemon recarregar sua configuração; é `SIGHUP` por padrão. Outro sinal é enviado para parar o processo do daemon; o padrão é `SIGTERM`, mas isso pode ser alterado definindo `sig_stop` apropriadamente. [NOTE] ==== Os nomes dos sinais devem ser especificados para o man:rc.subr[8] sem o prefixo `SIG`, como é mostrado no exemplo. A versão do FreeBSD do man:kill[1] pode reconhecer o prefixo `SIG`, mas as versões de outros tipos de sistema operacional não. ==== ➎➏ Realizar tarefas adicionais antes ou depois dos métodos padrão é fácil. Para cada argumento de comando suportado pelo nosso script, podemos definir o argumento `_precmd` e `_postcmd`. Esses comandos no man:sh[1] são invocados antes e depois do respectivo método, como é evidente em seus nomes. [NOTE] ==== Sobrescrever um método padrão com um `argumento _cmd` personalizado ainda não nos impede de fazer uso do `argumento _precmd` ou `argumento _postcmd` se precisarmos. Em particular, o primeiro é bom para verificar condições personalizadas e sofisticadas que devem ser atendidas antes de executar o comando em si. Usar o `argumento _precmd` junto com o `argumento _cmd` nos permite separar logicamente as verificações da ação. Não se esqueça de que você pode amontoar qualquer expressão válida do man:sh[1] nos métodos, pré e pós-comandos definidos por você. Apenas invocar uma função que faz com que o trabalho real seja um bom estilo na maioria dos casos, mas nunca deixe o estilo limitar sua compreensão do que está acontecendo por trás da cortina. ==== ➐ Se quisermos implementar argumentos customizados, que também podem ser considerados como _comandos_ para o nosso script, precisamos listá-los em `extra_commands` e fornecer métodos para manipulá-los. [NOTE] ==== O comando `reload` é especial. Por um lado, tem um método predefinido em man:rc.subr[8]. Por outro lado, `reload` não é oferecido por padrão. A razão é que nem todos os daemons usam o mesmo mecanismo de recarga e alguns não têm nada para recarregar. Portanto, precisamos solicitar explicitamente que a funcionalidade incorporada seja fornecida. Podemos fazer isso via `extra_commands`. O que obtemos do método padrão para `reload`? Muitas vezes, os daemons recarregam sua configuração na recepção de um sinal - normalmente, `SIGHUP`. Portanto, o man:rc.subr[8] tenta recarregar o daemon enviando um sinal para ele. O sinal é predefinido para `SIGHUP`, mas pode ser personalizado via `sig_reload`, caso necessário. ==== ➑⓮ Nosso script suporta dois comandos não padrão, `plugh` e `xyzzy`. Nós os vimos listados em `extra_commands`, e agora é hora de fornecer métodos para eles. O método para `xyzzy` é apenas embutido, enquanto que para `plugh` é implementado como a função `mumbled_plugh`. Comandos não padrão não são chamados durante a inicialização ou o desligamento. Geralmente eles são para a conveniência do administrador do sistema. Eles também podem ser usados de outros subsistemas, por exemplo, man:devd[8] se especificado em man:devd.conf[5]. A lista completa de comandos disponíveis pode ser encontrada na linha de uso impressa por man:rc.subr[8] quando o script é invocado sem argumentos. Por exemplo, aqui está a linha de uso do script em estudo: [source,shell] .... # /etc/rc.d/mumbled Uso: /etc/rc.d/mumbled [fast|force|one](start|stop|restart|rcvar|reload|plugh|xyzzy|status|poll) .... ⓭ Um script pode invocar seus próprios comandos padrão ou não padrão, se necessário. Isto pode parecer semelhante as funções de chamada, mas sabemos que comandos e funções de shell nem sempre são a mesma coisa. Por exemplo, `xyzzy` não é implementado como uma função aqui. Além disso, pode haver um pré-comando e um pós-comando, que devem ser chamados ordenadamente. Portanto, a maneira correta de um script executar seu próprio comando é por meio de man:rc.subr[8], conforme mostrado no exemplo. ➒ Uma função útil chamada `checkyesno` é fornecida por man:rc.subr[8]. Ele usa um nome de variável como argumento e retorna um código de saída zero se, e somente se, a variável estiver configurada como `YES`, ou `TRUE`, ou `ON`, ou `1`, sem distinção entre maiúsculas e minúsculas; um código de saída diferente de zero é retornado de outra forma. No último caso, a função testa a variável como sendo definida como `NO`,`FALSE`,`OFF` ou `0` insensível a maiúsculas e minúsculas; imprime uma mensagem de aviso se a variável contiver qualquer outra coisa, ou seja, lixo. Tenha em mente que para o man:sh[1] um código de saída zero significa verdadeiro e um código de saída diferente de zero significa falso. [IMPORTANT] ==== A função `checkyesno` recebe um __nome da variável__. Não passe o _valor_ expandido de uma variável para ele; não funcionará como esperado. O uso correto de `checkyesno` é: [.programlisting] .... if checkyesno mumbled_enable; then foo fi .... Pelo contrário, chamar `checkyesno` como mostrado abaixo não funcionará - pelo menos não como esperado: [.programlisting] .... if checkyesno "${mumbled_enable}"; then foo fi .... ==== ➓ [[rc-flags]] Podemos afetar os sinalizadores a serem passados para `$command` modificando `rc_flags` em `$start_precmd`. ⓫ Em certos casos, podemos precisar emitir uma mensagem importante que também deve ser enviada para o `syslog`. Isto pode ser feito facilmente com as seguintes funções man:rc.subr[8]: `debug`, `info`, `warn` e `err`. A última função, em seguida, sai do script com o código especificado. ⓬ Os códigos de saída dos métodos e seus pré-comandos não são apenas ignorados por padrão. Se o argumento `_precmd` retornar um código de saída diferente de zero, o método principal não será executado. Por sua vez, o `argumento_postcmd` não será invocado a menos que o método principal retorne um código de saída zero. [NOTE] ==== No entanto, o man:rc.subr[8] pode ser instruído a partir da linha de comando para ignorar esses códigos de saída e invocar todos os comandos, prefixando um argumento com `force`, como em `forcestart`. ==== [[rcng-hookup]] == Conectando um script ao framework rc.d Depois que um script foi escrito, ele precisa ser integrado em [.filename]#rc.d>#. O passo crucial é instalar o script em [.filename]#/etc/rc.d# (para o sistema base) ou [.filename]#/usr/local/etc/rc.d# (para ports). Ambos [.filename]#bsd.prog.mk# e [.filename]#bsd.port.mk# fornecer ganchos convenientes para isso, e geralmente você não precisa se preocupar com a propriedade e o modo adequado. Os scripts do sistema devem ser instalados a partir do [.filename]#src /etc/rc.d# através do [.filename]#Makefile# encontrado lá. Os scripts de porta podem ser instalados usando `USE_RC_SUBR` conforme descrito em link:{porters-handbook}#rc-scripts[no Manual do Porter]. No entanto, devemos considerar antecipadamente o local do nosso script na sequência de inicialização do sistema. O serviço manipulado pelo nosso script provavelmente depende de outros serviços. Por exemplo, um daemon de rede não pode funcionar sem as interfaces de rede e o roteamento em funcionamento. Mesmo que um serviço pareça não exigir nada, dificilmente pode ser iniciado antes que os sistemas de arquivos básicos tenham sido verificados e montados. Nós já mencionamos o man:rcorder[8]. Agora é hora de dar uma olhada de perto. Em poucas palavras, o man:rcorder[8] pega um conjunto de arquivos, examina seu conteúdo e imprime uma lista ordenada por dependência de arquivos do conjunto para `stdout`. O objetivo é manter as informações de dependência _dentro_ dos arquivos para que cada arquivo possa falar por si só. Um arquivo pode especificar as seguintes informações: * os nomes das "condições" (o que significa serviços para nós) que ele __fornece__; * os nomes das "condições" que ele __requer__; * os nomes das "condições" deste arquivo devem ser executados __antes__; * _palavras-chave adicionais_ que podem ser usadas para selecionar um subconjunto de todo o conjunto de arquivos (man:rcorder[8] podem ser instruídos através de opções para incluir ou omitir os arquivos com determinadas palavras-chave listadas.) Não é surpresa que man:rcorder[8] possa manipular apenas arquivos de texto com uma sintaxe próxima a de man:sh[1]. Ou seja, linhas especiais compreendidas por man:rcorder[8] se parecem com comentários man:sh[1]. A sintaxe de tais linhas especiais é bastante rígida para simplificar seu processamento. Veja man:rcorder[8] para detalhes. Além de usar linhas especiais do man:rcorder[8], um script pode insistir em sua dependência de outro serviço apenas iniciando-o forçadamente. Isso pode ser necessário quando o outro serviço é opcional e não será iniciado automaticamente porque o administrador do sistema o desativou por engano no man:rc.conf[5]. Com este conhecimento geral em mente, vamos considerar o simples script daemon aprimorado com coisas de dependência: [.programlisting] .... #!/bin/sh # PROVIDE: mumbled oldmumble <.> # REQUIRE: DAEMON cleanvar frotz <.> # BEFORE: LOGIN <.> # KEYWORD: nojail shutdown <.> . /etc/rc.subr name=mumbled rcvar=mumbled_enable command="/usr/sbin/${name}" start_precmd="${name}_prestart" mumbled_prestart() { if ! checkyesno frotz_enable && \ ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then force_depend frotz || return 1 <.> fi return 0 } load_rc_config $name run_rc_command "$1" .... Como antes, a análise detalhada segue: ➊ Esta linha declara os nomes das "condições" que nosso script fornece. Agora, outros scripts podem registrar uma dependência em nosso script por estes nomes. [NOTE] ==== Geralmente, um script especifica uma única condição fornecida. No entanto, nada nos impede de listar várias condições, por exemplo, por razões de compatibilidade. Em qualquer caso, o nome da condição principal, ou a única, `PROVIDE:` deve ser o mesmo que `${name}`. ==== ➋➌ Portanto, nosso script indica quais condições "" são fornecidas por outros scripts dos quais depende. De acordo com as linhas, nosso script pede ao man:rcorder[8] para colocá-lo após o(s) script(s) fornecendo [.filename]#DAEMON# e [.filename]#cleanvar#, mas antes disso prover [.filename]#LOGIN#. [NOTE] ==== A linha `BEFORE:` não deve ser abusada para contornar uma lista de dependências incompleta no outro script. O caso apropriado para usar o `BEFORE:` é quando o outro script não se importa com o nosso, mas nosso script pode fazer sua tarefa melhor se for executado antes do outro. Um típico exemplo da vida real são as interfaces de rede versus o firewall: embora as interfaces não dependam do firewall em realizar seu trabalho, a segurança do sistema se beneficiará do firewall estar pronto antes que haja qualquer tráfego de rede. Além das condições correspondentes a um único serviço, existem meta-condições e seus scripts "placeholder" usados para garantir que determinados grupos de operações sejam executados antes dos outros. Estes são denotados pelos nomes [.filename]#UPPERCASE#. Sua lista e finalidades podem ser encontradas em man:rc[8]. Tenha em mente que colocar um nome de serviço na linha `REQUIRE:` não garante que o serviço estará realmente em execução no momento em que nosso script for iniciado. O serviço necessário pode falhar ao iniciar ou simplesmente ser desativado em man:rc.conf[5]. Obviamente, o man:rcorder[8] não pode controlar tais detalhes, e o man:rc[8] também não fará isso. Consequentemente, o aplicativo iniciado por nosso script deve ser capaz de lidar com quaisquer serviços necessários indisponíveis. Em certos casos, podemos ajudá-lo conforme discutido <> ==== ➍ [[keywords]] Como lembramos do texto acima, as palavras-chave do man:rcorder[8] podem ser usadas para selecionar ou deixar alguns scripts. Ou seja, qualquer consumidor man:rcorder[8] pode especificar através das opções `-k` e `-s` que as palavras-chave estão na "keep list" e na "skip list", respectivamente. De todos os arquivos a serem classificados, o man:rcorder[8] selecionará apenas aqueles que tiverem uma palavra-chave da lista de manutenção (a menos que vazia) e não uma palavra-chave da lista de itens ignorados. No FreeBSD, o man:rcorder[8] é usado por [.filename]#/etc/rc# e [.filename]#/etc/rc.shutdown#. Esses dois scripts definem a lista padrão de palavras-chave do [.filename]#rc.d# do FreeBSD e seus significados da seguinte forma: ➎ [[forcedep]] Para começar, `force_depend` deve ser usado com muito cuidado. Geralmente é melhor revisar a hierarquia de variáveis de configuração para seus scripts [.filename]#rc.# se eles forem interdependentes. Se você ainda não pode fazer sem `force_depend`, o exemplo oferece uma expressão de como invocá-lo condicionalmente. No exemplo, nosso daemon `mumbled` requer que outro, `frotz`, seja iniciado antecipadamente. No entanto, `frotz` é opcional também; e man:rcorder[8] não sabe nada sobre esses detalhes. Felizmente, nosso script tem acesso a todas as variáveis man:rc.conf[5]. Se `frotz_enable` estiver como true, esperamos pelo melhor e dependemos de [.filename]#rc.d# para iniciar `frotz`. Caso contrário, nós forçadamente verificaremos o status de `frotz`. Finalmente, impomos nossa dependência ao `frotz` se ele não estiver sendo executado. Uma mensagem de aviso será emitida por `force_depend` porque ele deve ser chamado apenas se um erro de configuração for detectado. [[rcng-args]] == Dando mais flexibilidade a um script rc.d Quando chamado durante a inicialização ou desligamento, um script [.filename]#rc.d# deve agir em todo o subsistema pelo qual é responsável. Por exemplo, [.filename]#/etc/rc.d/netif# deve iniciar ou parar todas as interfaces de rede descritas por man:rc.conf[5]. Qualquer tarefa pode ser indicada exclusivamente por um único argumento de comando, como `start` ou `stop`. Entre a inicialização e o desligamento, os scripts [.filename]#rc.d# ajudam o administrador a controlar o sistema em execução, e é quando surge a necessidade de mais flexibilidade e precisão. Por exemplo, o administrador pode querer adicionar as configurações de uma nova interface de rede ao man:rc.conf[5] e então iniciá-lo sem interferir o funcionamento das interfaces existentes. Da próxima vez, o administrador pode precisar desligar uma única interface de rede. No espírito da linha de comando, o respectivo script [.filename]#rc.d# solicita um argumento extra, o nome da interface. Felizmente, man:rc.subr[8] permite passar qualquer número de argumentos para os métodos do script (dentro dos limites do sistema). Devido a isso, as alterações no próprio script podem ser mínimas. Como o man:rc.subr[8] pode obter acesso aos argumentos de linha de comando extra. Deveria pegá-los diretamente? Não por qualquer meio. Primeiro, uma função man:sh[1] não tem acesso aos parâmetros posicionais de seu chamador, mas o man:rc.subr[8] é apenas uma despedida de tais funções. Em segundo lugar, a boa maneira de [.filename]#rc.d# determina que é para o script principal decidir quais argumentos devem ser passados para seus métodos. Portanto, a abordagem adotada por man:rc.subr[8] é a seguinte: `run_rc_command` transmite todos os seus argumentos, mas o primeiro um para o respectivo método na íntegra. O primeiro, omitido, argumento é o nome do próprio método: `start`,`stop`, etc. Ele será deslocado por `run_rc_command`, então o que é `$2` na linha de comando original será apresentado como `$1` ao método, e assim por diante. Para ilustrar essa oportunidade, vamos modificar o script fictício primitivo para que suas mensagens dependam dos argumentos adicionais fornecidos. Aqui vamos nós: [.programlisting] .... #!/bin/sh . /etc/rc.subr name="dummy" start_cmd="${name}_start" stop_cmd=":" kiss_cmd="${name}_kiss" extra_commands="kiss" dummy_start() { if [ $# -gt 0 ]; then <.> echo "Greeting message: $*" else echo "Nothing started." fi } dummy_kiss() { echo -n "A ghost gives you a kiss" if [ $# -gt 0 ]; then <.> echo -n " and whispers: $*" fi case "$*" in *[.!?]) echo ;; *) echo . ;; esac } load_rc_config $name run_rc_command "$@" <.> .... Quais mudanças essenciais podemos notar no script? ➊ Todos os argumentos digitados após `start` podem terminar como parâmetros posicionais para o respectivo método. Podemos usá-los de qualquer maneira de acordo com nossa tarefa, habilidades e fantasia. No exemplo atual, apenas passamos todos eles para man:echo[1] como uma cadeia na linha seguinte - note `$*` entre aspas duplas. Aqui está como o script pode ser chamado agora: [source,shell] .... # /etc/rc.d/dummy start Nothing started. # /etc/rc.d/dummy start Hello world! Greeting message: Hello world! .... ➋ O mesmo se aplica a qualquer método que nosso script forneça, não apenas a um método padrão. Nós adicionamos um método customizado chamado `kiss`, e ele pode tirar proveito dos argumentos extras da mesma forma que o `start` tira. Por exemplo: [source,shell] .... # /etc/rc.d/dummy kiss A ghost gives you a kiss. # /etc/rc.d/dummy kiss Once I was Etaoin Shrdlu... A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu... .... ➌ Se quisermos apenas passar todos os argumentos extras para qualquer método, podemos simplesmente substituir `"$@"` por `"$ 1"` na última linha do nosso script, onde invocamos o `run_rc_command`. [IMPORTANT] ==== Um programador man:sh[1] deve entender a diferença sutil entre `$*` e `$@` como as formas de designar todos os parâmetros posicionais. Para sua discussão aprofundada, consulte um bom manual sobre programação de scripts man:sh[1]. _Não_ use estas expressões até que você as compreenda completamente, porque o uso incorreto delas resultará em scripts inseguros e contendo bugs. ==== [NOTE] ==== Atualmente, o `run_rc_command` pode ter um bug que o impede de manter os limites originais entre os argumentos. Ou seja, argumentos com espaços em branco incorporados podem não ser processados corretamente. O bug deriva do uso inadequado de `$*`. ==== [[rcng-furthur]] == Leitura adicional [[lukem]]http://www.mewburn.net/luke/papers/rc.d.pdf[O artigo original de Luke Mewburn] oferece uma visão geral do [.filename]#rc.d# e o raciocínio detalhado que o levou a suas decisões de design. Ele fornece informações sobre toda o framework do [.filename]#rc.d# e o seu lugar em um moderno sistema operacional BSD. [[manpages]]As páginas de manual man:rc[8], man:rc.subr[8] e man:rcorder[8] documentam os componentes do [.filename]#rc.d# com grande detalhe. Você não pode usar totalmente o poder do [.filename]#rc.d# sem estudar as páginas de manual e se referir a elas enquanto escreve seus próprios scripts. A sua principal fonte de inspiração são os exemplos da vida real, existentes em no [.filename]#/etc/rc.d# de um sistema vivo. Seu conteúdo é fácil e agradável de ler, porque a maioria dos cantos ásperos estão escondidos fundo no man:rc.subr[8]. Tenha em mente que os scripts [.filename]#/etc/rc.d# não foram escritos por anjos, então eles podem sofrer de bugs e decisões sub-ótimas de design. Agora você pode melhorá-los! diff --git a/documentation/content/pt-br/articles/releng/_index.adoc b/documentation/content/pt-br/articles/releng/_index.adoc index fccbb25c68..cbc26986a4 100644 --- a/documentation/content/pt-br/articles/releng/_index.adoc +++ b/documentation/content/pt-br/articles/releng/_index.adoc @@ -1,356 +1,357 @@ --- title: Engenharia de Release do FreeBSD authors: - author: Murray Stokely email: murray@FreeBSD.org webpage: https://people.FreeBSD.org/~murray/ trademarks: ["freebsd", "intel", "general"] --- = Engenharia de Release do FreeBSD :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :xrefstyle: full :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo -include::shared/pt-br/urls.adoc[] - ifeval::["{backend}" == "html5"] +include::shared/pt-br/urls.adoc[] :imagesdir: ../../../images/articles/releng/ endif::[] ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/releng/ endif::[] ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/releng/ endif::[] [.abstract-title] Resumo [NOTE] ==== Este documento está desatualizado e não descreve com precisão os procedimentos atuais de lançamentos da equipe de Engenharia de Release (Versão) do FreeBSD. É retido para fins históricos. Os procedimentos atuais usados pela equipe de Engenharia de Release do FreeBSD estão disponíveis no artigo link:{freebsd-releng}[Engenharia de Release do FreeBSD]. ==== Este artigo descreve a abordagem usada pela equipe de engenharia de release do FreeBSD para produzir versões do Sistema Operacional FreeBSD com qualidade de produção. Ele detalha a metodologia utilizada para as versões oficiais do FreeBSD e descreve as ferramentas disponíveis para aqueles interessados em produzir versões customizadas do FreeBSD para uso corporativo ou para uso em produtos comerciais. ''' toc::[] [[introduction]] == Introdução O desenvolvimento do FreeBSD é um processo muito aberto. O FreeBSD é composto por contribuições de milhares de pessoas em todo o mundo. O Projeto FreeBSD fornece acesso ao Subversion footnote:[Subversion, http://subversion.apache.org] para o público em geral para que outros possam ter acesso a mensagens de log, diffs (patches) entre branches (ramificações) de desenvolvimento e outros aprimoramentos de produtividade que o gerenciamento formal de código-fonte proporciona. Isso tem sido uma grande ajuda na atração de desenvolvedores talentosos para o FreeBSD. No entanto, acho que todos concordariam que o caos logo se manifestaria se o acesso para modificar o repositório principal fosse aberto a todos na Internet. Dessa forma, apenas um grupo "seleto" de quase 300 pessoas recebe acesso de escrita ao repositório do Subversion. Estes link:{contributors}#staff-committers[committers] footnote:[link:{contributors}#staff-committers[committers]] são normalmente as pessoas que fazem a maior parte do desenvolvimento do FreeBSD. Um https://www.FreeBSD.org/administration/#t-core[Core team]footnote:[https://www.FreeBSD.org/administration/#t-core[Core Team do FreeBSD]] eleito fornece algum nível de orientação sobre o projeto. O ritmo acelerado de desenvolvimento do `FreeBSD` torna a principal branch de desenvolvimento inadequada para o uso diário pelo público em geral. Em particular, são necessários esforços de estabilização para polir o sistema de desenvolvimento em uma release de qualidade apropriada para uso em ambiente produtivo. Para resolver este conflito, o desenvolvimento continua em várias trilhas paralelas. A principal branch de desenvolvimento é a _HEAD_ ou _trunk_ da nossa árvore do Subversion, conhecida como "FreeBSD-CURRENT" ou "-CURRENT" quando abreviado. Um conjunto de branches mais estáveis é mantido, e é conhecido como "FreeBSD-STABLE" ou "-STABLE" na forma abreviada. Todas as branchs ficam em um repositório principal do Subversion mantido pelo Projeto FreeBSD. O FreeBSD-CURRENT é a "vanguarda do desenvolvimento tecnológico" do FreeBSD, pelo qual todas as novas alterações entram no sistema pela primeira vez. O FreeBSD-STABLE é a branch de desenvolvimento a partir do qual as releases principais são feitas. Mudanças entram nesta branch em um ritmo diferente, e com a suposição geral de que elas foram primeiro para o FreeBSD-CURRENT e foram exaustivamente testadas por nossa comunidade de usuários. O termo _stable_ no nome da branch refere-se à estabilidade presumida da Interface Binária da Aplicação (ABI), que é prometida pelo projeto. Isso significa que um aplicativo de usuário compilado em uma versão mais antiga do sistema da mesma branch funciona em um sistema mais novo da mesma branch. A estabilidade do ABI melhorou muito em relação às versões anteriores. Na maioria dos casos, os binários dos sistemas _STABLE_ mais antigos são executados sem modificações em sistemas mais recentes, incluindo o __HEAD__, assumindo que as interfaces de gerenciamento do sistema não são usadas. No período intermediário entre as versões, snapshots semanais são construídos automaticamente pelas máquinas de build do Projeto FreeBSD e disponibilizados para download em `ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/`. A ampla disponibilidade de snapshots binários e a tendência da nossa comunidade de usuários para acompanhar o desenvolvimento do -STABLE com o Subversion e `"make buildworld"` footnote:[link:{handbook}#makeworld[Re-construindo o 'mundo']] ajuda a manter o FreeBSD-STABLE em uma condição muito confiável, mesmo antes que as atividades de garantia de qualidade aumentem na proximidade de um grande lançamento. Além dos snapshots de instalação no formato ISO, imagens semanais de máquinas virtuais também são fornecidas para uso com o VirtualBox, o qemu ou outros softwares populares de emulação. As imagens de máquinas virtuais podem ser baixadas em `ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/`. As imagens das máquinas virtuais tem aproximadamente 150MB compactadas com o man:xz[1] e contêm um sistema de arquivos esparso de 10GB quando atachado a uma máquina virtual. Relatórios de bugs e solicitações de recursos são enviados continuamente pelos usuários durante todo o ciclo da release. Os relatórios de problemas são inseridos em nosso banco de dados do Bugzilla por meio da interface da Web disponibilizada em https://www.freebsd.org/support/bugreports/[https://www.freebsd.org/support/bugreports/]. Para atender nossos usuários mais conservadores, versões individuais foram introduzidas com o FreeBSD 4.3. Estas branchs de versões são criadas pouco antes de uma liberação final ser feita. Após o lançamento, somente as correções e adições de segurança mais críticas são aplicadas na branch da versão. Além das atualizações do código fonte via Subversion, patchkits binários estão disponíveis para manter os sistemas nas branchs _releng/X.Y_ atualizadas. === O que Este Artigo Descreve As seções a seguir deste artigo descrevem: <>:: As diferentes fases do processo de engenharia de release que levam à criação do sistema atual. <>:: O processo de criação atual. <>:: Como o release base pode ser estendido por terceiros. <>:: Algumas das lições aprendidas através do lançamento do FreeBSD 4.4. <>:: Direções futuras de desenvolvimento. [[release-proc]] == Processos de Release (Versão) Novas versões do FreeBSD são liberadas a partir da branch -STABLE em intervalos de aproximadamente quatro meses. O processo de release do FreeBSD começa a se desenhar cerca de 70-80 dias antes da data de lançamento prevista, quando o engenheiro de versão envia um email para as listas de discussão de desenvolvimento para lembrar aos desenvolvedores que eles só têm 15 dias para integrar novas alterações antes do congelamento de código. Durante esse tempo, muitos desenvolvedores executam o que ficou conhecido como "MFC sweeps". MFC significa "Merge From CURRENT" e descreve o processo de fusão de uma alteração testada de nossa branch de desenvolvimento -CURRENT com a nossa branch -STABLE. A política do projeto requer que qualquer mudança seja aplicada pela primeira vez ao trunk, e aplicada às branches -STABLE após testes externos suficientes serem feitos pelos usuários no -CURRENT (espera-se que os desenvolvedores testem extensivamente a mudança antes de enviarem a mesma para o -CURRENT, mas é impossível para uma pessoa exercer todos os usos de um sistema operacional de propósito geral). O período mínimo de MFC é de 3 dias, que normalmente é usado apenas para correções de bugs triviais ou críticas. === Revisão de código Sessenta dias antes do lançamento previsto, o repositório de código entra um "congelamento de código". Durante esse tempo, todos os commits para a branch -STABLE devem ser aprovados pela equipe de engenharia de release (versão) mailto:re@FreeBSD.org[re@FreeBSD.org]. O processo de aprovação é tecnicamente aplicado por um "pre-commit hook". Os tipos de alterações permitidos durante esse período incluem: * Correções de bugs. * Atualizações de documentação. * Correções relacionadas à segurança de qualquer tipo. * Pequenas alterações nos drivers de dispositivos, como a adição de novos IDs de dispositivos. * Atualizações de driver dos fornecedores. * Qualquer mudança adicional que a equipe de engenharia de release julgue justificada, dado o risco potencial. Logo após o início do congelamento de código, uma imagem _BETA1_ é criada e liberada para testes generalizados. Durante o congelamento de código, pelo menos uma imagem beta ou um candidato a versão é lançado a cada duas semanas até que a versão final esteja pronta. Durante os dias que antecedem a versão final, a equipe de engenharia de release está em constante comunicação com a equipe de segurança, os mantenedores de documentação e os mantenedores de ports para garantir que todos os diferentes componentes necessários para uma versão bem-sucedida estejam disponíveis. Após a qualidade das imagens BETA ser satisfatória o suficiente, e nenhuma mudança grande e potencialmente arriscada estar planejada, a branch release é criada e as imagens _Release Candidate_ (RC) são construídas a partir da branch release, ao invés das Imagens BETA serem construidas da branch STABLE. Além disso, o congelamento na branch STABLE é suspenso e a branch de release entra em um "congelamento de código rígido", onde fica muito mais difícil justificar novas alterações no sistema, a menos que envolva uma correção séria de bug ou um problema de segurança. === Checklist Final para uma Release Quando várias imagens BETA já tiverem sido disponibilizadas para testes generalizados e todos os principais problemas tiverem sido resolvidos, o "polimento" da versão final pode começar. [[rel-branch]] ==== Criação da Branch (Ramificação) da Release (Versão) [NOTE] ==== Em todos os exemplos abaixo, `$FSVN` refere-se ao local do repositório Subversion do FreeBSD, `svn+ssh://svn.FreeBSD.org/base/`. ==== O layout das branchs do FreeBSD no Subversion é descrito no link:{committers-guide}#subversion-primer-base-layout[Guia do Commiter]. O primeiro passo na criação de uma branch é identificar a revisão do código fonte do `stable/_X_`, a partir do qual você deseja criar a nova _branch_. [source,shell] .... # svn log -v $FSVN/stable/9 .... O próximo passo é criar a _branch da release_ [source,shell] .... # svn cp $FSVN/stable/9@REVISION $FSVN/releng/9.2 .... Esta branch pode ser obtida com: [source,shell] .... # svn co $FSVN/releng/9.2 src .... [NOTE] ==== A criação das tags da branch `releng` e de `release` é feita pela https://www.FreeBSD.org/administration/#t-re[Equipe de Engenharia de Release]. ==== image::branches-head.png[Branch de Desenvolvimento do FreeBSD] image::branches-releng3.png[Branch FreeBSD 3.x STABLE] image::branches-releng4.png[Branch FreeBSD 4.x STABLE] image::branches-releng5.png[Branch FreeBSD 5.x STABLE] image::branches-releng6.png[Branch FreeBSD 6.x STABLE] image::branches-releng7.png[Branch FreeBSD 7.x STABLE] image::branches-releng8.png[Branch FreeBSD 8.x STABLE] image::branches-releng9.png[Branch FreeBSD 9.x STABLE] [[versionbump]] ==== Incrementando o número da versão Antes que a versão final possa ser marcada, construída e lançada, os seguintes arquivos precisam ser modificados para refletir a versão correta do FreeBSD: * [.filename]#doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml# * [.filename]#doc/en_US.ISO8859-1/books/porters-handbook/book.xml# * [.filename]#doc/en_US.ISO8859-1/htdocs/cgi/ports.cgi# * [.filename]#ports/Tools/scripts/release/config# * [.filename]#doc/shared/xml/freebsd.ent# * [.filename]#src/Makefile.inc1# * [.filename]#src/UPDATING# * [.filename]#src/gnu/usr.bin/groff/tmac/mdoc.local# * [.filename]#src/release/Makefile# * [.filename]#src/release/doc/en_US.ISO8859-1/shared/xml/release.dsl# * [.filename]#src/release/doc/shared/examples/Makefile.relnotesng# * [.filename]#src/release/doc/shared/xml/release.ent# * [.filename]#src/sys/conf/newvers.sh# * [.filename]#src/sys/sys/param.h# * [.filename]#src/usr.sbin/pkg_install/add/main.c# * [.filename]#doc/en_US.ISO8859-1/htdocs/search/opensearch/man.xml# As notas de versão e os arquivos de errata também precisam ser ajustados para a nova versão (na branch (ramificação) da release) e truncados apropriadamente (na branch stable/current): * [.filename]#src/release/doc/en_US.ISO8859-1/relnotes/common/new.xml# * [.filename]#src/release/doc/en_US.ISO8859-1/errata/article.xml# O Sysinstall deve ser atualizado para exibir o número de ports disponíveis e a quantidade de espaço em disco necessária para a Coleção de Ports. footnote:[Coleção de Ports do FreeBSD https://www.FreeBSD.org/ports] Esta informação é atualmente mantida em [.filename]#src/usr.sbin/bsdinstall/dist.c#. Após a release ter sido construida, vários arquivos devem ser atualizados para anunciar a versão para o mundo. Esses arquivos são relativos a `head/` dentro da árvore `doc/` do subversion. * [.filename]#share/images/articles/releng/branches-relengX.pic# * [.filename]#head/shared/xml/release.ent# * [.filename]#en_US.ISO8859-1/htdocs/releases/*# * [.filename]#en_US.ISO8859-1/htdocs/releng/index.xml# * [.filename]#share/xml/news.xml# Além disso, atualize o arquivo da "Árvore Genealógica do BSD": * [.filename]#src/shared/misc/bsd-family-tree# ==== Criando a Tag de Release Quando a versão final estiver pronta, o seguinte comando criará a tag `release/9.2.0`. [source,shell] .... # svn cp $FSVN/releng/9.2 $FSVN/release/9.2.0 .... Os gerentes de Documentação e do Ports são responsáveis por marcar suas respectivas árvores com a tag `tags/RELEASE_9_2_0`. Quando o comando `svn cp` do Subversion é usado para criar uma __tag de versão__, isso identifica o código fonte em um ponto específico no tempo. Criando tags, nós garantimos que futuros construtores de versões sempre poderão usar exatamente o mesmo código fonte que usamos para criar as releases oficiais do Projeto FreeBSD. [[release-build]] == Construção da Release (Versão) As "releases" do FreeBSD podem ser construídas por qualquer pessoa com uma máquina rápida e acesso a um repositório de código-fonte. (Isso deveria ser todo mundo, já que oferecemos acesso ao Subversion! Veja a seção sobre link:{handbook}#svn[Subversion] no Handbook para detalhes.) O _único_ requisito especial é que o dispositivo man:md[4] esteja disponível. Se o dispositivo não estiver carregado em seu kernel, então o módulo do kernel deve ser carregado automaticamente quando o man:mdconfig[8] for executado durante a fase de criação da mídia de boot. Todas as ferramentas necessárias para construir uma release estão disponíveis no repositório Subversion em [.filename]#src/release#. Essas ferramentas visam fornecer uma maneira consistente de construir versões do FreeBSD. Uma release completa pode ser construída com apenas um único comando, incluindo a criação de imagens ISO adequadas para gravação em CD-ROM ou DVD e um diretório para instalação por FTP. A pagina de manual man:release[7] documenta completamente o script `src/release/generate-release.sh` que é usado para construir uma release. O `generate-release.sh` é um invólucro em torno do target do Makefile: `make release`. === Construindo uma Release (Versão) A página de manual man:release[7] documenta os comandos exatos necessários para construir uma Release do FreeBSD. As seguintes sequências de comandos podem construir uma versão 9.2.0: [source,shell] .... # cd /usr/src/release # sh generate-release.sh release/9.2.0 /local3/release .... Depois de executar esses comandos, todos os arquivos preparados da versão estarão disponíveis no diretório [.filename]#/local3/release/R#. O release [.filename]#Makefile# pode ser dividido em várias etapas distintas. * Criação de um ambiente de sistema limpo em uma hierarquia de diretório separada com "`make installworld`". * Checkout do Subversion de uma versão limpa do código fonte do sistema, da documentação e e da coleção de ports na hierarquia de build do release. * Popula o [.filename]#/etc# e o [.filename]#/dev# no ambiente chrooted (Processo de transferir o diretório root para outro lugar). * Faz chroot na hierarquia de build (construção) da release, para tornar mais difícil para o ambiente externo corromper essa construção. * Execução do comando `make world` no ambiente chrooted. * Compilação dos binários relacionados ao Kerberos. * Compilação do kernel [.filename]#GENERIC#. * Criação uma árvore de diretórios temporários onde as distribuições binárias serão compiladas e empacotadas. * Compilação e instalação do toolchain necessário para converter o fonte da documentação (SGML) em HTML e demais documentos de texto que acompanharão a versão. * Compilação e instalação da documentação propriamente dita (manuais do usuário, tutoriais, notas de versão, listas de compatibilidade de hardware e assim por diante). * Empacotamento dos tarballs de distribuição dos binários e fontes. * Criação da hierarquia de instalação por FTP. * _(opcionalmente)_ Criação das imagens ISO para mídia de CDROM/DVD. Para obter maiores informações sobre a infraestrutura de criação de versões, consulte man:release[7]. [NOTE] ==== É importante remover qualquer configuração específica do seu servidor do [.filename]#/etc/make.conf#. Por exemplo, seria imprudente distribuir binários que foram compilados em um sistema com `CPUTYPE` configurado para um processador específico. ==== === Software Contribuído ("ports") A https://www.FreeBSD.org/ports[Coleção de Ports do FreeBSD] é uma coleção de mais de 24.000 pacotes de software de terceiros disponíveis para o FreeBSD. A Equipe de Gerenciamento de Ports mailto:portmgr@FreeBSD.org[portmgr@FreeBSD.org] é responsável por manter uma árvore de ports consistente que pode ser usada para criar os pacotes binários que acompanham as releases oficiais do FreeBSD. === ISOs das Releases (Versões) Começando no FreeBSD 4.4, o Projeto FreeBSD decidiu liberar todas as quatro imagens ISO que eram vendidas anteriormente nas distribuições "oficiais" em CDROM pela __BSRi/Wind River Systems/FreeBSD Mall__. Cada um dos quatro discos deve conter um arquivo [.filename]#README.TXT# que explica o conteúdo do disco, um arquivo [.filename]#CDROM.INF# que fornece metadados do disco para que o man:bsdinstall[8] possa validar e usar o conteúdo, e um arquivo [.filename]#filename.txt# que fornece um manifesto para o disco. Este _manifesto_ pode ser criado com um simples comando: [source,shell] .... /stage/cdrom# find . -type f | sed -e 's/^\.\///' | sort > filename.txt .... Os requisitos específicos de cada CD são descritos abaixo. ==== Disco 1 O primeiro disco é quase completamente criado por `make release`. As únicas alterações que devem ser feitas no diretório [.filename]#disc1# são a adição de um diretório [.filename]#tools# e tantos pacotes de software de terceiros quanto couberem no disco. O diretório [.filename]#tools# contém software que permite aos usuários criar disquetes de instalação a partir de outros sistemas operacionais. Esse disco deve ser inicializado para que os usuários dos PCs modernos não precisem criar disquetes de instalação. Se um kernel customizado do FreeBSD precisa ser incluído, então o man:bsdinstall[8] e o man:release[7] deve ser atualizado para incluir instruções de instalação. O código relevante está contido em [.filename]#src/release# e [.filename]#src/usr.sbin/bsdinstall#. Especificamente, os arquivos [.filename]#src/release/Makefile#, [.filename]#dist.c#, [.filename]#dist.h#, [.filename]#menus.c# , [.filename]#install.c#, e [.filename]#Makefile# precisarão ser atualizados em [.filename]#src/usr.sbin/bsdinstall#. Opcionalmente, você pode escolher atualizar o [.filename]#bsdinstall.8#. ==== Disco 2 O segundo disco também é largamente criado por `make release`. Este disco contém um "live filesystem" que pode ser usado por man:bsdinstall[8] para solucionar problemas de instalação do FreeBSD. Este disco deve ser inicializável e também deve conter uma cópia compactada do repositório CVS no diretório [.filename]#CVSROOT# e demos de software comercial no diretório [.filename]#commerce#. ==== Suporte para vários volumes O Sysinstall suporta a instalação de pacotes a partir de vários volumes. Isso requer que cada disco tenha um arquivo [.filename]#INDEX# contendo todos os pacotes em todos os volumes de um conjunto, junto com um campo extra que indica em qual volume esse pacote específico está. Cada volume no conjunto também deve ter a variável `CD_VOLUME` definida no arquivo [.filename]#cdrom.inf# para que o bsdinstall possa informar qual volume é qual. Quando um usuário tentar instalar um pacote que não esteja no disco atual, o bsdinstall solicitará que o usuário insira o disco apropriado. [[distribution]] == Distribuição [[dist-ftp]] === Sites FTP Quando a release for totalmente testada e empacotada para distribuição, o site FTP principal deverá ser atualizado. Os sites de FTP públicos oficiais do FreeBSD são todos espelhos de um servidor principal que está acessível somente a outros sites FTP. Este site é conhecido como `ftp-master`. Quando a release estiver pronta, os seguintes arquivos devem ser modificados no `ftp-master`: [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/#:: O diretório FTP instalável como saída de `make release`. [.filename]#/pub/FreeBSD/ports/arch/packages-X.Y-release/#:: O pacote completo criado para esta versão. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools#:: Um link simbólico para [.filename]#../../../tools#. [.filename]#/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages#:: Um link simbólico para [.filename]#../../../ports/arch/packages-X.Y-release#. [.filename]#/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso#:: As imagens ISO. O "*" é o [.filename]#disc1#, [.filename]#disc2#, etc. Somente se houver um [.filename]#disc1# e houver um CD alternativo para o primeiro disco de instalação (por exemplo, uma instalação simplificada sem sistema de janelas) também pode haver um [.filename]#mini#. Para mais informações sobre a arquitetura do sistema de espelhamento dos sites de FTP para distribuição do FreeBSD, por favor veja o artigo link:{hubs}[Espelhando o FreeBSD]. Pode levar de muitas horas a dois dias após a atualização do `ftp-master` antes que a maioria dos sites de FTP da camada 1 tenham o novo software, dependendo se um conjunto de pacotes foi ou não carregado ao mesmo tempo. É imperativo que os engenheiros de release coordenem com os http://lists.FreeBSD.org/mailman/listinfo/mirror-announce[administradores dos sites espelho do FreeBSD] antes de anunciar a disponibilidade geral de novo software nos sites FTP. Idealmente, o pacote da release deve ser carregado pelo menos quatro dias antes do dia de lançamento. Os bits da release devem ser carregados entre 24 e 48 horas antes do horário de lançamento planejado com as permissões de arquivo "other" desativadas. Isso permitirá que os sites espelho façam o download, mas o público em geral não poderá baixá-los dos sites espelho. Um e-mail deve ser enviado para a lista dos http://lists.FreeBSD.org/mailman/listinfo/mirror-announce[administradores do site espelho do FreeBSD] no momento em que os bits da release forem publicados, informando que a release foi preparada e informando o horário em que os sites espelho devem começar a permitir o acesso. Certifique-se de incluir um fuso horário com a hora, por exemplo, torná-lo relativo ao GMT. [[dist-cdrom]] === Replicação do CD-ROM Em breve: Dicas para enviar ISOs do FreeBSD para um replicador e medidas de garantia de qualidade a serem tomadas. [[extensibility]] == Extensibilidade Embora o FreeBSD forme um sistema operacional completo, não há nada que force você a usar o sistema exatamente como o empacotamos para distribuição. Tentamos projetar o sistema para ser o mais extensível possível, de modo que ele possa servir como uma plataforma na qual outros produtos comerciais possam ser construídos. A única "regra" que temos sobre isso é que se você for distribuir o FreeBSD com mudanças não triviais, nós encorajamos você a documentar suas melhorias! A comunidade do FreeBSD só pode ajudar a suportar usuários do software que fornecemos. Nós certamente encorajamos a inovação na forma de ferramentas avançadas de instalação e administração, por exemplo, mas você não esperar que respondamos perguntas sobre isso. === Usando o script `bsdinstall` A ferramenta de instalação e configuração do sistema FreeBSD, man:bsdinstall[8], pode ser programada para fornecer instalações automatizadas para sites grandes. Essa funcionalidade pode ser usada em conjunto com Intel(R) PXE footnote:[link:{handbook}#network-pxe-nfs[Network PXE NFS]] para inicializar sistemas da rede. [[lessons-learned]] == Lições Aprendidas do FreeBSD 4.4 O processo de engenharia de release do 4.4 começou formalmente em 1º de agosto de 2001. Após essa data, todos os commits da branch `RELENG_4` do FreeBSD tiveram que ser explicitamente aprovados pela Equipe de Engenharia de Release mailto:re@FreeBSD.org[re@FreeBSD.org]. O primeiro release candidate para a arquitetura x86 foi lançado em 16 de agosto, seguido por mais 4 candidatos a versão que antecederam a versão final em 18 de setembro. O agente de segurança esteve muito envolvido na última semana do processo, pois vários problemas de segurança foram encontrados nos candidatos anteriores. Um total de mais de _500_ e-mails foram enviados para a Equipe de Engenharia de Release mailto:re@FreeBSD.org[re@FreeBSD.org] em pouco mais de um mês. Nossa comunidade de usuários deixou bem claro que a segurança e a estabilidade de uma versão do FreeBSD não devem ser sacrificadas por quaisquer prazos auto-impostos ou datas-alvo de lançamento. O projeto FreeBSD cresceu tremendamente ao longo de sua existência e a necessidade de procedimentos padronizados de engenharia de versões nunca foi tão aparente. Isso se tornará ainda mais importante à medida que o FreeBSD for portado para novas plataformas. [[future]] == Direções futuras É imperativo que nossas atividades de engenharia de release sejam escaladas com nossa crescente base de usuários. Nessa linha, estamos trabalhando muito para documentar os procedimentos envolvidos na produção de versões do FreeBSD. * _Paralelismo_ - Algumas partes da compilação da release são, na verdade, "embaraçosamente paralelas". A maioria das tarefas é muito intensiva em I/O, portanto, ter várias unidades de disco de alta velocidade é realmente mais importante do que usar vários processadores para acelerar o processo do `make release`. Se vários discos forem usados para hierarquias diferentes no ambiente man:chroot[2], o CVS checkout das árvores do [.filename]#ports# e do [.filename]#doc# podem estar acontecendo simultaneamente como o `make world` em outro disco. Usar uma solução `RAID` (hardware ou software) pode diminuir significativamente o tempo de compilação geral. * _Releases cross-building_ - Criação do release IA-64 ou Alpha em hardware x86? Use o comando `make TARGET=ia64 release`. * _Teste de regressão_ - Precisamos de melhores testes automatizados para o FreeBSD. * _Ferramentas de instalação_ - Nosso programa de instalação há muito tempo ultrapassou à sua expectativa de vida útil. Vários projetos estão em desenvolvimento para fornecer um mecanismo de instalação mais avançado. O projeto libh era um desses projetos que visava fornecer um novo e inteligente framework de pacotes e um programa de instalação GUI. [[ackno]] == Agradecimentos Eu gostaria de agradecer a Jordan Hubbard por me dar a oportunidade de assumir algumas das responsabilidades de engenharia de release do FreeBSD 4.4 e também por todo o seu trabalho ao longo dos anos fazendo do FreeBSD o que é hoje. É claro quea Release não teria sido possível sem todo o trabalho relacionado a release feito por Satoshi Asami mailto:asami@FreeBSD.org[asami@FreeBSD.org], Steve Price mailto:steve@FreeBSD.org[steve@FreeBSD.org], Bruce A. Mah mailto:bmah@FreeBSD.org[bmah@FreeBSD.org], Nik Clayton mailto:nik@FreeBSD.org[nik@FreeBSD.org], David O'Brien mailto:obrien@FreeBSD.org[obrien@FreeBSD.org], Kris Kennaway mailto:kris@FreeBSD.org[kris@FreeBSD.org], John Baldwin mailto:jhb@FreeBSD.org[jhb@FreeBSD.org] e o resto da comunidade de desenvolvimento do FreeBSD. Eu também gostaria de agradecer a Rodney Grimes mailto:rgrimes@FreeBSD.org[rgrimes@FreeBSD.org], Poul-Henning Kamp mailto:phk@FreeBSD.org[phk@FreeBSD.org], e outros que trabalharam nas ferramentas de engenharia de release nos primeiros dias do FreeBSD. Este artigo foi influenciado por documentos de engenharia de release do CSRG footnote:[Marshall Kirk McKusick, Michael J. Karels e Keith Bostic: A Engenharia de Release do 4.3BSD], o Projeto NetBSD, footnote:[Documentação do desenvolvedor do NetBSD: Engenharia de Release http://www.NetBSD.org/developers/releng/index.html], e as notas de processo de engenharia de release propostas por John Baldwin. footnote:[Proposta de engenharia de Release do FreeBSD de John Baldwin https://people.FreeBSD.org/~jhb/docs/releng.txt] diff --git a/documentation/content/pt-br/articles/remote-install/_index.adoc b/documentation/content/pt-br/articles/remote-install/_index.adoc index 683e94912c..d0695b03b9 100644 --- a/documentation/content/pt-br/articles/remote-install/_index.adoc +++ b/documentation/content/pt-br/articles/remote-install/_index.adoc @@ -1,331 +1,341 @@ --- title: Instalação Remota do Sistema Operacional FreeBSD Sem um Console Remoto authors: - author: Daniel Gerzo email: danger@FreeBSD.org copyright: 2008 Projeto de Documentação do FreeBSD releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "general"] --- = Instalação Remota do Sistema Operacional FreeBSD Sem um Console Remoto :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este artigo documenta a instalação remota do sistema operacional FreeBSD quando o console do sistema remoto não está disponível. A idéia principal por trás deste artigo é o resultado de uma colaboração com Martin Matuska mailto:mm@FreeBSD.org[mm@FreeBSD.org] com informações valiosas fornecidas por Paweł Jakub Dawidek mailto:pjd@FreeBSD.org[pjd@FreeBSD.org]. ''' toc::[] [[background]] == Background Existem muitos provedores de hospedagem de servidores no mundo, mas poucos deles oferecem suporte oficial ao FreeBSD. Eles geralmente fornecem suporte para uma distribuição Linux(R) para ser instalada nos servidores que eles oferecem. Em alguns casos, estas empresas instalarão sua distribuição Linux(R) preferida se você solicitá-la. Usando esta opção, tentaremos instalar o FreeBSD. Em outros casos, eles podem oferecer um sistema de recuperação para ser usado em uma emergência. É possível usá-la para os nossos propósitos também. Este artigo aborda as etapas básicas de instalação e configuração necessárias para inicializar uma instalação remota do FreeBSD com suporte para RAID-1 e ZFS. [[intro]] == Introdução Esta seção resumirá o objetivo deste artigo e explicará melhor o que é tratado aqui. As instruções incluídas neste artigo beneficiarão aqueles usuários que usam serviços fornecidos por provedores de colocation que não suportam o FreeBSD. [.procedure] . Como mencionamos na seção <>, muitas das empresas de hospedagem de servidores renomadas fornecem algum tipo de sistema de recuperação, que é inicializado a partir de sua LAN e acessível por SSH. Eles normalmente fornecem esse suporte para ajudar seus clientes a consertar sistemas operacionais quebrados. Como este artigo explicará, é possível instalar o FreeBSD com a ajuda destes sistemas de recuperação. + . A próxima seção deste artigo descreverá como configurar e compilar uma versão mínima do FreeBSD na máquina local. Essa versão eventualmente será executada na máquina remota a partir de um ramdisk, o que nos permitirá instalar um sistema operacional completo do FreeBSD a partir de um espelho FTP usando o utilitárioSysinstall. . O restante deste artigo descreverá o procedimento de instalação em si, bem como a configuração do sistema de arquivos ZFS. [[requirements]] === Requisitos Para continuar com sucesso, você deve: * Ter um sistema operacional acessível pela rede com acesso SSH * Entender o processo de instalação do FreeBSD * Familiarizar-se com o utilitário man:sysinstall[8] * Ter a imagem ISO de instalação do FreeBSD ou o CD de instalação à mão [[preparation]] == Preparação - mfsBSD Antes que o FreeBSD possa ser instalado no sistema de destino, é necessário construir a imagem mínima do sistema operacional FreeBSD que será inicializada a partir do disco rígido. Dessa forma, o novo sistema pode ser acessado a partir da rede e o restante da instalação pode ser feito sem acesso remoto ao console do sistema. O conjunto de ferramentas mfsBSD pode ser usado para construir uma pequena imagem do FreeBSD. Como o nome mfsBSD sugere ("mfs" significa "sistema de arquivos em memória"), a imagem resultante é executada inteiramente de um ramdisk. Graças a este recurso, a manipulação de discos rígidos não será limitada, portanto, será possível instalar um sistema operacional completo do FreeBSD. A http://mfsbsd.vx.sk/[página inicial] do mfsBSD inclui links para a versão mais recente do conjunto de ferramentas. Por favor, note que os detalhes de como o mfsBSD funciona internamente e como tudo se encaixa está além do escopo deste artigo. O leitor interessado deve consultar a documentação original do mfsBSD para mais detalhes. Faça o download e extraia a versão mais recente do mfsBSD e altere seu diretório de trabalho para o diretório em que os scripts mfsBSD residirão: [source,shell] .... # fetch http://mfsbsd.vx.sk/release/mfsbsd-2.1.tar.gz # tar xvzf mfsbsd-2.1.tar.gz # cd mfsbsd-2.1/ .... [[mfsbsd-config]] === Configuração do mfsBSD Antes de inicializar o mfsBSD, algumas opções importantes de configuração precisam ser definidas. O mais importante que temos que acertar é, naturalmente, a configuração da rede. O método mais adequado para configurar opções de rede depende se sabemos de antemão o tipo de interface de rede que usaremos e o driver da interface de rede a ser carregado para o nosso hardware. Vamos ver como o mfsBSD pode ser configurado em ambos os casos. Outra coisa importante para definir é a senha do usuário `root`. Isto pode ser feito editando o [.filename]#conf/loader.conf#. Por favor, veja os comentários incluídos no arquivo. ==== O método [.filename]#conf/interfaces.conf# Quando a placa de rede instalada é desconhecida, é possível usar os recursos de detecção automática do mfsBSD. Os scripts de inicialização do mfsBSD podem detectar o driver correto a ser usado, com base no endereço MAC da interface, se configurarmos as seguintes opções em [.filename]#conf/interfaces.conf#: [.programlisting] .... mac_interfaces="ext1" ifconfig_ext1_mac="00:00:00:00:00:00" ifconfig_ext1="inet 192.168.0.2/24" .... Não esqueça de adicionar a informação `defaultrouter` ao [.filename]#conf/rc.conf#: [.programlisting] .... defaultrouter="192.168.0.1" .... ==== O método [.filename]#conf/rc.conf# Quando o driver da interface de rede é conhecido, é mais conveniente usar [.filename]#conf/rc.conf# para opções de rede. A sintaxe deste arquivo é a mesma usada no arquivo padrão man:rc.conf[5] do FreeBSD. Por exemplo, se você souber que uma interface de rede man:re[4] estará disponível, você pode definir as seguintes opções em [.filename]#conf/rc.conf#: [.programlisting] .... defaultrouter="192.168.0.1" ifconfig_re0="inet 192.168.0.2/24" .... [[mfsbsd-build]] === Construindo uma imagem do mfsBSD O processo de construção de uma imagem mfsBSD é bastante simples. O primeiro passo é montar o CD de instalação do FreeBSD, ou a imagem ISO de instalação em [.filename]#/cdrom#. Por exemplo, neste artigo vamos supor que você tenha baixado o ISO do FreeBSD 10.1-RELEASE. Montar esta imagem ISO no diretório [.filename]#/cdrom# é fácil de se fazer com o utilitário man:mdconfig[8]: [source,shell] .... # mdconfig -a -t vnode -u 10 -f FreeBSD-10.1-RELEASE-amd64-disc1.iso # mount_cd9660 /dev/md10 /cdrom .... Como as versões recentes do FreeBSD não contêm conjuntos de distribuição regulares, é necessário extrair os arquivos de distribuição do FreeBSD dos arquivos de distribuição localizados na imagem ISO: [source,shell] .... # mkdir DIST # tar -xvf /cdrom/usr/freebsd-dist/base.txz -C DIST # tar -xvf /cdrom/usr/freebsd-dist/kernel.txz -C DIST .... Em seguida, construa a imagem mfsBSD inicializável: [source,shell] .... # make BASE=DIST .... [NOTE] ==== O make acima deve ser executado a partir do nível superior da árvore de diretórios do mfsBSD, por exemplo, [.filename]#~/mfsbsd-2.1/#. ==== === Inicializando o mfsBSD Agora que a imagem mfsBSD está pronta, ela deve ser carregada para o sistema remoto executando o sistema de recuperação ou uma distribuição Linux(R) pré-instalada. A ferramenta mais adequada para essa tarefa é o scp: [source,shell] .... # scp disk.img root@192.168.0.2:. .... Para inicializar corretamente a imagem mfsBSD, ela deve ser colocada no primeiro dispositivo (inicializável) da máquina em questão. Isso pode ser feito usando este exemplo, desde que o [.filename]#sda# seja o primeiro dispositivo de disco inicializável: [source,shell] .... # dd if=/root/disk.img of=/dev/sda bs=1m .... Se tudo correu bem, a imagem deve estar agora no MBR do primeiro dispositivo e a máquina pode ser reinicializada. Observe a máquina inicializar corretamente com a ferramenta man:ping[8]. Uma vez que tenha retornado on-line, deve ser possível acessá-la com o man:ssh[1] como o usuário `root` usando a senha configurada. [[installation]] == Instalação do sistema operacional do FreeBSD O mfsBSD foi inicializado com sucesso e deve ser possível efetuar login através do man:ssh[1]. Esta seção descreverá como criar e rotular os slices, configurar o gmirror para o RAID-1 e como usar o Sysinstall para instalar uma distribuição mínima do sistema operacional FreeBSD. === Preparação de Discos Rígidos A primeira tarefa é alocar espaço em disco para o FreeBSD, ou seja: criar slices e partições. Obviamente, o sistema atualmente em execução é totalmente carregado na memória do sistema e, portanto, não haverá problemas com a manipulação dos discos rígidos. Para completar esta tarefa, é possível usar Sysinstall ou man:fdisk[8] em conjunto com o man:bsdlabel[8]. No início, marque todos os discos do sistema como vazios. Repita o seguinte comando para cada disco rígido: [source,shell] .... # dd if=/dev/zero of=/dev/ad0 count=2 .... Em seguida, crie as slices e atribua um label usando sua ferramenta preferida. Embora seja considerado mais fácil usar o Sysinstall, um método poderoso e provavelmente com menos bugs será usar as ferramentas padrões de console UNIX(R), como o man:fdisk[8] e o man:bsdlabel[8], o qual também será abordado nesta seção. A primeira opção está bem documentada no capítulo link:{handbook}#install-steps[Instalando o FreeBSD] do Handbook do FreeBSD. Como foi mencionado na introdução, este artigo apresentará como configurar um sistema com recursos RAID-1 e ZFS. Nossa configuração consistirá de uma pequena partição [.filename]#/# (root) , de um dataset composto por um [.filename]#/usr# e um [.filename]#/var# , todos espelhados com o man:gmirror[8], e o restante do espaço em disco alocado para um sistema de arquivos man:zpool[8] espelhado do ZFS. Por favor, observe que o sistema de arquivos ZFS será configurado depois que o sistema operacional FreeBSD for instalado e inicializado com sucesso. O exemplo a seguir descreverá como criar slices e labels, inicializar o man:gmirror[8] em cada partição e como criar um sistema de arquivos UFS2 em cada partição espelhada: [source,shell] .... # fdisk -BI /dev/ad0 <.> # fdisk -BI /dev/ad1 # bsdlabel -wB /dev/ad0s1 <.> # bsdlabel -wB /dev/ad1s1 # bsdlabel -e /dev/ad0s1 <.> # bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt && bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt <.> # gmirror label root /dev/ad[01]s1a <.> # gmirror label var /dev/ad[01]s1d # gmirror label usr /dev/ad[01]s1e # gmirror label -F swap /dev/ad[01]s1b <.> # newfs /dev/mirror/root <.> # newfs /dev/mirror/var # newfs /dev/mirror/usr .... <.> Crie uma slice cobrindo todo o disco e inicialize o código de inicialização contido no setor 0 do disco fornecido. Repita este comando para todos os discos rígidos no sistema. <.> Escreva um label padrão para cada disco, incluindo o código de bootstrap. <.> Agora, edite manualmente o label do disco fornecido. Consulte a página de manual do man:bsdlabel[8] para descobrir como criar partições. Crie as partições `a` para o sistema de arquivos [.filename]#/# (root), `b` para swap, `d` para [.filename]#/var#, `e` para [.filename]#/usr# e finalmente `f`, que será usado posteriormente para o ZFS. <.> Importe o label recém-criado para o segundo disco rígido, para que ambos os discos sejam rotulados da mesma maneira. <.> Inicialize o man:gmirror[8] em cada partição. <.> Note que `-F` é usado para a partição de swap. Isso instrui o man:gmirror[8] a assumir que o dispositivo está no estado consistente após a falha de energia/sistema. <.> Crie um sistema de arquivos UFS2 em cada partição espelhada. === Instalação do sistema Esta é a parte mais importante. Esta seção irá descrever como instalar a distribuição mínima do FreeBSD nos discos rígidos que preparamos na seção anterior. Para atingir este objetivo, todos os sistemas de arquivos precisam ser montados para que o Sysinstall possa gravar o conteúdo do FreeBSD nos discos rígidos: [source,shell] .... # mount /dev/mirror/root /mnt # mkdir /mnt/var /mnt/usr # mount /dev/mirror/var /mnt/var # mount /dev/mirror/usr /mnt/usr .... Quando terminar, inicie o man:sysinstall[8]. Selecione a instalação [.guimenuitem]#Personalizada# no menu principal. Selecione [.guimenuitem]#Opções# e pressione kbd:[Enter]. Com a ajuda das teclas direcionais, mova o cursor para o item `Install Root`, pressione kbd:[Espaço] e altere-o para [.filename]#/mnt#. Pressione kbd:[Enter] para enviar suas alterações e sair do menu [.guimenuitem]#Opções# pressionando kbd:[q]. [WARNING] ==== Note que este passo é muito importante e se for ignorado, o Sysinstall não poderá instalar o FreeBSD. ==== Vá para o menu [.guimenuitem]#Distributions#, mova o cursor com as teclas de seta para `Minimal` e selecione-o pressionando kbd:[Space]. Este artigo usa a distribuição mínima para salvar o tráfego de rede, porque o próprio sistema será instalado por ftp. Saia deste menu escolhendo `Exit`. [NOTE] ==== Os menus [.guimenuitem]#Partition# e [.guimenuitem]#Label# serão ignorados, pois são inúteis agora. ==== No menu [.guimenuitem]#Media#, selecione `FTP`. Selecione o espelho mais próximo e deixe o Sysinstall assumir que a rede já está configurada. Você retornará ao menu [.guimenuitem]#Personalizar#. Finalmente, realize a instalação do sistema selecionando a última opção, [.guimenuitem]#Commit#. Saia do sysinstall quando terminar a instalação. === Etapas pós-instalação O sistema operacional do FreeBSD deve estar instalado agora; no entanto, o processo ainda não está concluído. É necessário executar algumas etapas pós-instalação para permitir que o FreeBSD inicialize no futuro e consiga efetuar o login no sistema. Você deve agora executar man:chroot[8] para o sistema recém-instalado para concluir a instalação. Use o seguinte comando: [source,shell] .... # chroot /mnt .... Para completar nosso objetivo, execute estas etapas: * Copie o kernel `GENERIC` para o diretório [.filename]#/boot/kernel#: + [source,shell] .... # cp -Rp /boot/GENERIC/* /boot/kernel .... * Crie os arquivos [.filename]#/etc/rc.conf#, [.filename]#/etc/resolv.conf# e [.filename]#/etc/fstab#. Não se esqueça de configurar corretamente as informações de rede e ativar o sshd em [.filename]#/etc/rc.conf#. O conteúdo do [.filename]#/etc/fstab# será semelhante ao seguinte: + [.programlisting] .... # Device Mountpoint FStype Options Dump Pass# /dev/mirror/swap none swap sw 0 0 /dev/mirror/root / ufs rw 1 1 /dev/mirror/usr /usr ufs rw 2 2 /dev/mirror/var /var ufs rw 2 2 /dev/cd0 /cdrom cd9660 ro,noauto 0 0 .... * Crie o [.filename]#/boot/loader.conf# com o seguinte conteúdo: + [.programlisting] .... geom_mirror_load="YES" zfs_load="YES" .... * Execute o seguinte comando, que disponibilizará o ZFS na próxima inicialização: + [source,shell] .... # echo 'zfs_enable="YES"' >> /etc/rc.conf .... * Adicione usuários adicionais ao sistema usando a ferramenta man:adduser[8]. Não se esqueça de adicionar um usuário ao grupo `wheel` para que você possa obter acesso root após a reinicialização. * Verifique todas as suas configurações. O sistema deve estar pronto para a próxima inicialização. Use o comando man:reboot[8] para reinicializar seu sistema. [[zfs]] == ZFS Se o seu sistema sobreviveu à reinicialização, agora deve ser possível efetuar login. Bem-vindo à nova instalação do FreeBSD, executada remotamente sem o uso de um console remoto! O único passo restante é configurar o man:zpool[8] e criar algum sistemas de arquivos man:zfs[8]. Criar e administrar o ZFS é muito simples. Primeiro, crie um pool espelhado: [source,shell] .... # zpool create tank mirror /dev/ad[01]s1f .... Em seguida, crie alguns sistemas de arquivos: [source,shell] .... # zfs create tank/ports # zfs create tank/src # zfs set compression=gzip tank/ports # zfs set compression=on tank/src # zfs set mountpoint=/usr/ports tank/ports # zfs set mountpoint=/usr/src tank/src .... Isso é tudo. Se você está interessado em mais detalhes sobre o ZFSno FreeBSD, por favor consulte a seção https://wiki.freebsd.org/ZFS[ZFS] do o Wiki do FreeBSD. diff --git a/documentation/content/pt-br/articles/serial-uart/_index.adoc b/documentation/content/pt-br/articles/serial-uart/_index.adoc index ea57e431f7..7f06b2880a 100644 --- a/documentation/content/pt-br/articles/serial-uart/_index.adoc +++ b/documentation/content/pt-br/articles/serial-uart/_index.adoc @@ -1,1021 +1,1031 @@ --- title: Tutorial sobre Comunicações Seriais e UART authors: - author: Frank Durda email: uhclem@FreeBSD.org releaseinfo: "$FreeBSD$" trademarks: ["freebsd", "microsoft", "general"] --- = Tutorial sobre Comunicações Seriais e UART :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo +ifeval::["{backend}" == "html5"] include::shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] + +ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] +endif::[] [.abstract-title] Resumo Este artigo fala sobre o uso de hardware serial com o FreeBSD. ''' toc::[] [[uart]] == A UART: O que é e como funciona _Copyright (C) 1996 Frank Durda IV mailto:uhclem@FreeBSD.org[uhclem@FreeBSD.org], Todos os direitos reservados. 13 de Janeiro de 1996._ O controlador UART (Universal Asynchronous Receiver / Transmitter) é o componente chave do subsistema de comunicação serial de um computador. O UART pega bytes de dados e transmite os bits individuais de forma seqüencial. No destino, um segundo UART reúne os bits em bytes completos. A transmissão serial é comumente usada com modems e para comunicação entre computadores, terminais e outros dispositivos sem rede. Existem duas formas primárias de transmissão serial: Síncrona e Assíncrona. Dependendo dos modos suportados pelo hardware, o nome do subsistema de comunicação geralmente incluirá um `A` se ele suportar comunicações assíncronas, e um `S` se ele suportar Comunicações síncronas. Ambas as formas são descritas abaixo. Algumas siglas comuns são: [.blockquote] UART Universal Asynchronous Receiver/Transmitter [.blockquote] USART Universal Synchronous-Asynchronous Receiver/Transmitter === Transmissão Serial Síncrona A transmissão serial síncrona requer que o emissor e o receptor compartilhem um clock entre si, ou que o remetente forneça um sinal estroboscópico ou outro sinal de tempo para que o receptor saiba quando deve "ler" o próximo bit dos dados. Na maioria das formas de comunicação serial síncrona, se não houver dados disponíveis em um dado instante para transmitir, um caractere de preenchimento deve ser enviado para que os dados sejam sempre transmitidos. A comunicação síncrona é geralmente mais eficiente, pois somente os bits de dados são transmitidos entre o emissor e o receptor, e a comunicação síncrona pode ser mais cara se fios e circuitos extras forem necessários para compartilhar um sinal de relógio entre o emissor e o receptor. Uma forma de transmissão síncrona é usada com impressoras e dispositivos de disco fixo em que os dados são enviados em um conjunto de fios enquanto um clock ou strobe é enviado em um fio diferente. Impressoras e dispositivos de disco fixo normalmente não são dispositivos seriais porque a maioria dos padrões de interface de disco fixo envia uma palavra inteira de dados para cada sinal de clock ou de strobe usando um fio separado para cada bit da palavra. Na indústria de PCs, esses são conhecidos como dispositivos paralelos. O hardware de comunicação serial padrão no PC não suporta operações síncronas. Este modo é descrito aqui apenas para fins de comparação. === Transmissão Serial Assíncrona A transmissão assíncrona permite que os dados sejam transmitidos sem que o emissor tenha que enviar um sinal de relógio ao receptor. Em vez disso, o remetente e o receptor devem concordar com os parâmetros de tempo de antecedência e bits especiais são adicionados a cada palavra, os quais são usados para sincronizar as unidades de envio e recebimento. Quando uma palavra é dada ao UART para uma transmissão assíncrona, um bit chamado "Start Bit" é adicionado ao início de cada palavra que deve ser transmitida. O Start Bit é usado para alertar o receptor de que uma palavra de dados está prestes a ser enviada e para forçar o clock do receptor a sincronizar-se com o clock do transmissor. Estes dois clocks devem ser precisos o suficiente para não ter um desvio de frequência em mais de 10% durante a transmissão dos bits restantes na palavra. (Esse requisito foi definido nos dias das teleimpressoras mecânicas e é facilmente atendido pelos equipamentos eletrônicos modernos.) Após o Start Bit, os bits individuais da palavra de dados são enviados, com o Bit Menos Significativo (LSB) sendo enviado primeiro. Cada bit na transmissão é transmitido exatamente pelo mesmo período de tempo que todos os outros bits, e o receptor "olha" para o fio aproximadamente na metade do período atribuído a cada bit para determinar se o bit é um `1` ou um `0`. Por exemplo, se forem necessários dois segundos para enviar cada bit, o receptor examinará o sinal para determinar se é um `1` ou um `0` após ter passado um segundo, ele esperará dois segundos e examinará o valor do próximo bit, e assim por diante. O remetente não sabe quando o receptor "olhou" para o valor do bit. O remetente só sabe quando o clock diz para começar a transmitir o próximo bit da palavra. Quando toda a palavra de dados foi enviada, o transmissor pode adicionar um Bit de Paridade que o transmissor gera. O Bit de Paridade pode ser usado pelo receptor para executar uma verificação de erros simples. Então pelo menos um Stop Bit é enviado pelo transmissor. Quando o receptor recebeu todos os bits na palavra de dados, ele pode verificar os bits de paridade (tanto o remetente quanto o receptor devem concordar se um bit de paridade deve ser usado), e então o receptor procura um Stop Bit. Se o Stop Bit não aparecer quando é suposto aparecer, o UART considera a palavra inteira como ilegível e irá relatar um Framing Error para o processador do host quando a palavra de dados é lida. A causa comum de um Framing Error é que os clocks do emissor e do receptor não estavam sendo executados na mesma velocidade ou que o sinal foi interrompido. Independentemente de os dados terem sido recebidos corretamente ou não, o UART descarta automaticamente os Bits de Start, Paridade e Stop. Se o emissor e o receptor forem configurados de forma idêntica, esses bits não serão passados ​​para o host. Se outra palavra estiver pronta para transmissão, o Start Bit da nova palavra pode ser enviado assim que o Stop Bit da palavra anterior for enviado. Como os dados assíncronos são "auto-sincronizados", se não houver dados para transmitir, a linha de transmissão pode ficar inativa. === Outras funções UART Além do trabalho básico de conversão de dados de paralelo para serial para transmissão e de serial para paralelo na recepção, um UART normalmente fornecerá circuitos adicionais para sinais que podem ser usados ​​para indicar o estado da mídia de transmissão, e para regular o fluxo de dados no caso de o dispositivo remoto não estar preparado para aceitar mais dados. Por exemplo, quando o dispositivo conectado à UART é um modem, o modem pode informar a presença de uma operadora na linha telefônica enquanto o computador pode instruir o modem a reinicializar a si mesmo ou a não atender chamadas, aumentando ou diminuindo mais um desses sinais extras. A função de cada um desses sinais adicionais é definida no padrão EIA RS232-C. === Os padrões RS232-C e V.24 Na maioria dos sistemas de computador, o UART é conectado a um circuito que gera sinais que atendem à especificação EIA RS232-C. Há também um padrão CCITT chamado V.24 que reflete as especificações incluídas no RS232-C. ==== Atribuições de bit RS232-C (marcas e espaços) No RS232-C, um valor de `1` é chamado de `Mark` e um valor de `0` é chamado de `Space`. Quando uma linha de comunicação está inativa, a linha é chamada de "Marking", ou seja, está transmitindo o valor `1` continuamente. O bit de início sempre tem um valor de `0` (um space). O bit de parada sempre tem um valor de `1` (uma mark). Isso significa que sempre haverá uma transição Mark (1) para Space (0) na linha no início de cada palavra, mesmo quando várias palavras forem transmitidas de volta para trás. Isso garante que o remetente e o destinatário possam ressincronizar seus relógios independentemente do conteúdo dos bits de dados que estão sendo transmitidos. O tempo inativo entre os bits de Stop e Start não precisa ser um múltiplo exato (incluindo zero) da taxa de bits do link de comunicação, mas a maioria dos UARTs é projetada dessa maneira para simplificar. No RS232-C, o sinal "Marking" (a `1`) é representado por uma tensão entre -2 VDC e -12 VDC, e um sinal "Spacing" (um `0`) é representado por uma tensão entre 0 e +12 VDC. O transmissor deve enviar +12 VDC ou -12 VCC, e o receptor deve permitir alguma perda de tensão em cabos longos. Alguns transmissores em dispositivos de baixa potência (como computadores portáteis) às vezes usam apenas +5 VCC e -5 VCC, mas esses valores ainda são aceitáveis ​​para um receptor RS232-C, desde que os comprimentos dos cabos sejam curtos. ==== Sinal de quebra RS232-C O RS232-C também especifica um sinal chamado de `Break` (quebra), que é causado pelo envio de valores contínuos de espaçamento (sem bits de início ou de parada). Quando não há eletricidade presente no circuito de dados, a linha é considerada como enviando um `Break`. O sinal `Break` deve ter uma duração maior que o tempo que leva para enviar um byte completo mais os bits Start, Stop e Paridade. A maioria das UARTs pode distinguir entre um Framing Error e um intervalo, mas se a UART não puder fazer isso, a detecção de Framing Error pode ser usada para identificar quebras. Nos dias das teleimpressoras, quando numerosas impressoras em todo o país eram conectadas em série (como serviços de notícias), qualquer unidade poderia causar um `Break` abrindo temporariamente todo o circuito de modo que nenhuma corrente fluísse. Isso foi usado para permitir que um local com notícias urgentes interrompesse algum outro local que estava enviando informações no momento. Nos sistemas modernos existem dois tipos de sinais de quebra. Se o Break for maior que 1,6 segundos, será considerado um "Modem Break", e alguns modems podem ser programados para encerrar a conversa e colocar no gancho ou entrar no modo de comando dos modems quando o modem detectar este sinal. Se a quebra for menor que 1,6 segundos, significa uma quebra de dados e cabe ao computador remoto responder a esse sinal. Às vezes essa forma de quebra é usada como um sinal de Atenção ou Interrupção e às vezes é aceita como um substituto para o caractere ASCII CONTROL-C. Marcas e espaços também são equivalentes a "furos" e "sem furos" em sistemas de fita de papel. [NOTE] ==== As quebras não podem ser geradas a partir da fita de papel ou de qualquer outro valor de byte, uma vez que os bytes são sempre enviados com bit Start e Stop. A UART geralmente é capaz de gerar o sinal de espaçamento contínuo em resposta a um comando especial do processador host. ==== ==== Dispositivos RS232-C DTE e DCE A especificação RS232-C define dois tipos de equipamento: o Data Terminal Equipment (DTE) e o Data Carrier Equipment (DCE). Normalmente, o dispositivo DTE é o terminal (ou computador) e o DCE é um modem. Em toda a linha telefônica, no outro extremo de uma conversa, o modem receptor também é um dispositivo DCE e o computador conectado a esse modem é um dispositivo DTE. O dispositivo DCE recebe sinais nos pinos que o dispositivo DTE transmite e vice-versa. Quando dois dispositivos DTE ou DCE devem ser conectados sem utilizar um modem ou um tradutor de mídia similar entre eles, um modem NULL deve ser usado. O modem NULL reorganiza eletricamente o cabeamento para que a saída do transmissor seja conectada à entrada do receptor no outro dispositivo e vice-versa. Traduções semelhantes são executadas em todos os sinais de controle, de modo que cada dispositivo veja o que acha que são sinais de DCE (ou DTE) do outro dispositivo. O número de sinais gerados pelos dispositivos DTE e DCE não é simétrico. O dispositivo DTE gera menos sinais para o dispositivo DCE do que o dispositivo DTE recebe do DCE. ==== Atribuições de pinos RS232-C A especificação EIA RS232-C (e o equivalente ITU, V.24) requer um conector de vinte e cinco pinos (geralmente um DB25) e define a finalidade da maioria dos pinos nesse conector. No IBM Personal Computer e em sistemas semelhantes, um subconjunto de sinais RS232-C é fornecido por meio de conectores de nove pinos (DB9). Os sinais que não estão incluídos no conector do PC lidam principalmente com a operação síncrona, e esse modo de transmissão não é suportado pelo UART que a IBM selecionou para uso no IBM PC. Dependendo do fabricante do computador, um DB25, um DB9 ou ambos os tipos de conectores podem ser usados ​​para comunicações RS232-C. (O IBM PC também usa um conector DB25 para a interface de impressora paralela, o que causa alguma confusão.) Abaixo está uma tabela das atribuições de sinal RS232-C nos conectores DB25 e DB9. [.informaltable] [cols="1,1,1,1,1,1,1", frame="none", options="header"] |=== | Pinos DB25 RS232-C | Pinos DB9 IBM PC | Símbolo do Circuito EIA | Símbolo do Circuito CCITT | Nome Comum | Fonte de sinal | Descrição |1 |- |AA |101 |PG/FG |- |Quadro / aterramento de proteção |2 |3 |BA |103 |TD |DTE |Transmit Data |3 |2 |BB |104 |RD |DCE |Receive Data |4 |7 |CA |105 |RTS |DTE |Request to Send |5 |8 |CB |106 |CTS |DCE |Clear to Send |6 |6 |CC |107 |DSR |DCE |Data Set Ready |7 |5 |AV |102 |SG/GND |- |Signal Ground |8 |1 |CF |109 |DCD/CD |DCE |Data Carrier Detect |9 |- |- |- |- |- |Reserved for Test |10 |- |- |- |- |- |Reserved for Test |11 |- |- |- |- |- |Reserved for Test |12 |- |CI |122 |SRLSD |DCE |Sec. Recv. Line Signal Detector |13 |- |SCB |121 |SCTS |DCE |Secondary Clear to Send |14 |- |SBA |118 |DST |DTE |Secondary Transmit Data |15 |- |DB |114 |TSET |DCE |Trans. Sig. Element Timing |16 |- |SBB |119 |SRD |DCE |Secondary Received Data |17 |- |DD |115 |RSET |DCE |Receiver Signal Element Timing |18 |- |- |141 |LOOP |DTE |Local Loopback |19 |- |SCA |120 |SRS |DTE |Secondary Request to Send |20 |4 |CD |108.2 |DTR |DTE |Data Terminal Ready |21 |- |- |- |RDL |DTE |Remote Digital Loopback |22 |9 |CE |125 |RI |DCE |Ring Indicator |23 |- |CH |111 |DSRS |DTE |Data Signal Rate Selector |24 |- |DA |113 |TSET |DTE |Trans. Sig. Element Timing |25 |- |- |142 |- |DCE |Test Mode |=== === Bits, Baud e Simbolos Baud é uma medida de velocidade de transmissão em comunicação assíncrona. Devido aos avanços na tecnologia de comunicação por modem, esse termo é frequentemente mal utilizado na descrição das taxas de dados em dispositivos mais recentes. Tradicionalmente, uma taxa de transmissão representa o número de bits que estão realmente sendo enviados pela mídia, não a quantidade de dados que é realmente movida de um dispositivo DTE para outro. A contagem de Baud inclui os bits de Start, Stop e Paridade que são gerados pelo UART de envio e removidos pelo UART de recebimento. Isso significa que palavras de dados de sete bits na verdade levam 10 bits para serem completamente transmitidas. Portanto, um modem capaz de mover 300 bits por segundo de um lugar para outro normalmente só pode mover 30 palavras de 7 bits se a Paridade for usada e um bit de Start e Stop estiver presente. Se palavras de dados de 8 bits são usadas e bits de paridade também são usados, a taxa de dados cai para 27,27 palavras por segundo, porque agora leva 11 bits para enviar as palavras de oito bits, e o modem ainda envia apenas 300 bits por segundo. A fórmula para converter bytes por segundo em uma taxa de transmissão e vice-versa era simples até que os modems de correção de erros apareceram. Esses modems recebem o fluxo serial de bits da UART no computador host (mesmo quando os modems internos são usados, os dados ainda são frequentemente serializados) e convertem os bits de volta em bytes. Esses bytes são então combinados em pacotes e enviados pela linha telefônica usando um método de transmissão síncrona. Isso significa que os bits de Stop, Start e Paridade adicionados pelo UART no DTE (o computador) foram removidos pelo modem antes da transmissão pelo modem de envio. Quando esses bytes são recebidos pelo modem remoto, o modem remoto adiciona bits de Start, Stop e paridade às palavras, converte-os em um formato serial e envia-os para o UART receptor no computador remoto, que retira o Start, Stop e bits de paridade. A razão pela qual todas essas conversões extras são feitas é para que os dois modems possam executar a correção de erros, o que significa que o modem receptor pode solicitar ao modem de envio para reenviar um bloco de dados que não foi recebido com a soma de verificação correta. Essa verificação é feita pelos modems, e os dispositivos DTE geralmente não sabem que o processo está ocorrendo. Ao separar os bits de Start, Stop e Paridade, os bits adicionais de dados que os dois modems devem compartilhar entre si para executar a correção de erros são praticamente ocultados da taxa de transmissão efetiva vista pelo equipamento DTE de envio e recebimento. Por exemplo, se um modem enviar dez palavras de 7 bits para outro modem sem incluir os bits Start, Stop e Paridade, o modem de envio poderá adicionar 30 bits de suas próprias informações que o modem receptor pode usar para corrigir erros. sem afetar a velocidade de transmissão dos dados reais. O uso do termo Baud é ainda mais confuso pelos modems que executam compressão. Uma única palavra de 8 bits transmitida pela linha telefônica pode representar uma dúzia de palavras que foram transmitidas para o modem de envio. O modem de recebimento irá expandir os dados de volta ao seu conteúdo original e passar esses dados para o DTE de recebimento. Os modems modernos também incluem buffers que permitem que a taxa na qual os bits se movem pela linha telefônica (do DCE para o DCE) seja uma velocidade diferente da velocidade que os bits se movem entre o DTE e o DCE em ambas as extremidades da conversação. Normalmente, a velocidade entre o DTE e o DCE é maior que a velocidade do DCE para o DCE devido ao uso de compactação pelos modems. Como o número de bits necessários para descrever um byte variou durante a viagem entre as duas máquinas, mais as diferentes velocidades de bits por segundo usadas nos links DTE-DCE e DCE-DCE, o uso do termo Baud para descrever a velocidade geral de comunicação causa problemas e pode deturpar a velocidade real de transmissão. Então Bits Por Segundo (bps) é o termo correto a ser usado para descrever a taxa de transmissão na interface DCE para DCE e Baud ou Bits Por Segundo são termos aceitáveis ​​para uso quando uma conexão é feita entre dois sistemas com uma conexão com fio ou se estiver em uso um modem que não esteja executando correção de erros ou compactação. Os modernos modems de alta velocidade (2400, 9600, 14.400 e 19.200bps) na realidade ainda operam a 2400 ou abaixo de 2400 baud, ou mais precisamente, 2400 símbolos por segundo. O modem de alta velocidade é capaz de codificar mais bits de dados em cada Symbol usando uma técnica chamada Constellation Stuffing, é por isso que a taxa efetiva de bits por segundo do modem é maior, mas o modem continua a operar dentro da largura de banda limitada de áudio que o sistema telefônico fornece. Modems operando a 28.800 e velocidades mais altas têm taxas variáveis ​​de Symbol, mas a técnica é a mesma. === O computador pessoal IBM e o UART Começando com o IBM Personal Computer original, a IBM selecionou o National Semiconductor INS8250 UART para uso no adaptador IBM PC Paralelo/Serial. Gerações subsequentes de computadores compatíveis da IBM e de outros fornecedores continuaram a usar o INS8250 ou versões aprimoradas da família UART da National Semiconductor. ==== Árvore Genealógica da National Semiconductor UART Houve várias versões e gerações subseqüentes do INSART50 UART. Cada versão principal está descrita abaixo. [.programlisting] .... INS8250 -> INS8250B \ \ \-> INS8250A -> INS82C50A \ \ \-> NS16450 -> NS16C450 \ \ \-> NS16550 -> NS16550A -> PC16550D .... INS8250:: Esta parte foi usada no IBM PC original e no IBM PC/XT. O nome original para esta parte era o INS8250 ACE (Elemento de Comunicação Assíncrona) e ele era feito com tecnologia NMOS. + O 8250 usa oito portas de I/O e tem um envio de um byte e um buffer de recebimento de um byte. Esta UART original tem várias "race conditions" e outras falhas. O IBM BIOS original incluia código para contornar essas falhas, mas isso tornava o BIOS dependente das falhas estarem presentes, portanto, componentes subsequentes como o 8250A, 16450 ou 16550 não podiam ser usados no IBM PC original ou no IBM PC/XT. INS8250-B:: Esta é a velocidade mais lenta do INS8250 feito a partir da tecnologia NMOS. Ele contém os mesmos problemas que o INS8250 original. INS8250A:: Uma versão melhorada do INS8250 usando a tecnologia XMOS com várias falhas funcionais corrigidas. O INS8250A foi usado inicialmente em computadores clones de PC por fornecedores que usavam projetos de BIOS "limpos". Devido às correções no chip, este componente não pode ser usado com um BIOS compatível com o INS8250 ou o INS8250B. INS82C50A:: Esta é uma versão CMOS (baixo consumo de energia) do INS8250A e possui características funcionais semelhantes. NS16450:: O mesmo que o NS8250A com melhorias para que possa ser usado com projetos de barramento de CPU mais rápidos. A IBM usou esse componente no IBM AT e atualizou o IBM BIOS para não depender mais dos erros no INS8250. NS16C450:: Esta é uma versão CMOS (baixo consumo de energia) do NS16450. NS16550:: O mesmo que NS16450 com um buffer de envio e recebimento de 16 bytes, mas o design do buffer era falho e não podia ser usado com segurança. NS16550A:: O mesmo que NS16550 com as falhas de buffer corrigidas. O 16550A e seus sucessores se tornaram o projeto UART mais popular na indústria de PCs, principalmente devido à sua capacidade de lidar de forma confiável com taxas de dados mais altas em sistemas operacionais com tempos de resposta de interrupção lentos. NS16C552:: Este componente consiste em dois UARTs CMOS NS16C550A em um único chip. PC16550D:: O mesmo que NS16550A com falhas sutis corrigidas. Esta é a revisão D da família 16550 e é o mais recente projeto disponível da National Semiconductor. ==== O NS16550AF e o PC16550D são a mesma coisa A National reorganizou seu sistema de numeração de peças há alguns anos e o NS16550AFN não existe mais com esse nome. (Se você tiver um NS16550AFN, observe o código de data da peça, que é um número de quatro dígitos que geralmente começa com nove. Os dois primeiros dígitos do número são o ano, e os dois últimos dígitos são a semana do ano em que a peça foi fabricada. Se você tem um NS16550AFN, ele provavelmente tem alguns anos.) Os novos números são como PC16550DV, com pequenas diferenças nas letras de sufixo, dependendo do material da embalagem e sua forma. (Uma descrição do sistema de numeração pode ser encontrada abaixo.) É importante entender que em algumas lojas, você pode pagar US$ 15 por um NS16550AFN fabricado em 1990 e no próximo bin encontrar as novas peças PC16550DN com pequenas correções que o National fez desde que a peça AFN estava em produção, o PC16550DN foi provavelmente feito nos últimos seis meses e custa metade (tão baixo quanto US$ 5 se comprado em volume) do NS16550AFN porque ele está prontamente disponível. Como o fornecimento de chips NS16550AFN continua encolhendo, o preço provavelmente continuará aumentando até que mais pessoas descubram e aceitem que o PC16550DN realmente tem a mesma função que o número de peça antigo. ==== Sistema de Numeração de Peças da National Semiconductor Os números de peça mais antigos NS__nnnnnrqp__ agora são do formato PC__nnnnnrgp__. O _r_ é o campo de revisão. A revisão atual do 16550 da National Semiconductor é `D`. O _p_ é o campo que define o tipo de encapsulamento. Os tipos são: [.informaltable] [cols="1,1,1", frame="none"] |=== |"F" |QFP |(quad flat pack) L lead type |"N" |DIP |(dual inline package) through hole straight lead type |"V" |LPCC |(lead plastic chip carrier) J lead type |=== O _g_ é o campo de classificação do produto. Se um `I` precede a letra do tipo de encapsulamento, ele indica uma parte de classe "industrial", que possui especificações mais altas que uma parte padrão, mas não tão alta quanto o componente Especificação Militar (Milspec) . Este é um campo opcional. Então, o que costumávamos chamar de NS16550AFN (Pacote DIP) agora é chamado de PC16550DN ou PC16550DIN. === Outros fornecedores e UARTs semelhantes Ao longo dos anos, o 8250, o 8250A, o 16450 e o 16550 foram licenciados ou copiados por outros fornecedores de chips. No caso do 8250, 8250A e 16450, o circuito exato (o "megacell") foi licenciado para muitos fornecedores, incluindo a Western Digital e a Intel. Outros fornecedores realizaram engenharia reversa da peça ou produziram emulações que tiveram comportamento semelhante. Nos modems internos, o projetista de modem freqüentemente emula o 8250A/16450 com o microprocessador de modem, e o UART emulado frequentemente terá um buffer oculto que consiste em várias centenas de bytes. Por causa do tamanho do buffer, essas emulações podem ser tão confiáveis ​​quanto uma 16550A em sua capacidade de lidar com dados de alta velocidade. No entanto, a maioria dos sistemas operacionais ainda relatará que o UART é apenas um 8250A ou 16450, e pode não fazer uso efetivo do buffer extra presente no UART emulado, a menos que drivers especiais sejam usados. Alguns fabricantes de modem são motivados pelas forças do mercado a abandonar um design que possui centenas de bytes de buffer e, em vez disso, usam uma UART 16550A para que o produto compare favoravelmente nas comparações de mercado, embora o desempenho efetivo possa ser reduzido por essa ação. Um equívoco comum é que todas as partes com "16550A" escritas nelas são idênticas no desempenho. Existem diferenças e, em alguns casos, falhas definitivas na maioria desses clones 16550A. Quando o NS16550 foi desenvolvido, a National Semiconductor obteve várias patentes sobre o projeto e também limitou o licenciamento, tornando mais difícil para outros fornecedores fornecer um chip com características semelhantes. Por causa das patentes, projetos de engenharia reversa e emulações tiveram que evitar infringir as reivindicações cobertas pelas patentes. Posteriormente, essas cópias quase nunca funcionam exatamente da mesma forma que a NS16550A ou a PC16550D, que são as peças que a maioria dos fabricantes de computadores e modems deseja comprar, mas às vezes não estão dispostas a pagar o preço necessário para obter a peça genuína. Algumas das diferenças nas peças do clone 16550A não são importantes, enquanto outras podem impedir que o dispositivo seja usado com um determinado sistema operacional ou driver. Essas diferenças podem aparecer ao usar outros drivers ou quando ocorrem determinadas combinações de eventos que não foram bem testadas ou consideradas no driver Windows(R). Isso ocorre porque a maioria dos fornecedores de modem e de fabricantes de clones do 16550 usam os drivers da Microsoft do Windows(R) para Workgroups 3.11 e Microsoft(R)MS-DOS(R) como o principal teste de compatibilidade com o NS16550A. Esse critério excessivamente simplista e significa que se um sistema operacional diferente for usado, poderão surgir problemas devido a diferenças sutis entre os clones e os componentes genuínos. A National Semiconductor disponibilizou um programa chamado COMTEST que realiza testes de compatibilidade independentemente de qualquer driver do sistema operacional. Deve ser lembrado que o propósito deste tipo de programa é demonstrar as falhas nos produtos dos concorrentes, de modo que o programa reportará diferenças importantes e extremamente sutis no comportamento da peça que está sendo testada. Em uma série de testes realizados pelo autor deste documento em 1994, componentes fabricados pela National Semiconductor, TI, StarTech e CMD, bem como megacells e emulações incorporadas em modems internos foram testados com o COMTEST. Uma contagem de diferença para alguns desses componentes está listada abaixo. Como esses testes foram realizados em 1994, eles podem não refletir o desempenho atual do produto de um determinado fornecedor. Deve-se notar que o COMTEST normalmente aborta quando um número excessivo ou certos tipos de problemas são detectados. Como parte desse teste, o COMTEST foi modificado para não abortar, independentemente de quantas diferenças fossem encontradas. [.informaltable] [cols="1,1,1", frame="none", options="header"] |=== | Fornecedor | Número da peça | Erros (também conhecidos como "diferenças") |National |(PC16550DV) |0 |National |(NS16550AFN) |0 |National |(NS16C552V) |0 |TI |(TL16550AFN) |3 |CMD |(16C550PE) |19 |StarTech |(ST16C550J) |23 |Rockwell |Modem de referência com 16550 interno ou uma emulação (RC144DPi / C3000-25) |117 |Sierra |Modem com um 16550 interno (SC11951/SC11351) |91 |=== [NOTE] ==== Até o momento, o autor deste documento não encontrou nenhuma peça não-National que relate diferença zero usando o programa COMTEST. Também deve ser notado que a National teve cinco versões do 16550 ao longo dos anos e as partes mais novas se comportam de maneira um pouco diferente do NS16550AFN clássico que é considerado o benchmark para funcionalidade. O COMTEST parece fechar os olhos para as diferenças dentro da linha de produto da National e não relata nenhum erro nas peças da National (exceto para o original 16550) mesmo quando há erratas oficiais que descrevem erros nas revisões A, B e C das partes, então este viés no COMTEST deve ser levado em consideração. ==== É importante entender que uma simples contagem de diferenças do COMTEST não revela muito sobre quais diferenças são importantes e quais não são. Por exemplo, cerca de metade das diferenças relatadas nos dois modems listados acima que têm UARTs internas foram causadas pelos clones UARTs que não suportam modos de caractere de cinco e seis bits. Todos os UARTs 16550, 16450 e 8250 reais suportam esses modos e o COMTEST verifica a funcionalidade desses modos, de modo que mais de cinquenta diferenças são relatadas. No entanto, quase nenhum modem moderno suporta caracteres de cinco ou seis bits, particularmente aqueles com recursos de correção de erros e compressão. Isso significa que as diferenças relacionadas aos modos de caractere de cinco e seis bits podem ser desconsideradas. Muitas das diferenças que o COMTEST reporta têm a ver com o tempo. Em muitos projetos de clones, quando o host lê de uma porta, os bits de status em alguma outra porta podem não ser atualizados na mesma quantidade de tempo (alguns mais rápidos, alguns mais lentos) que um NS16550AFN _real_ e o COMTEST procura por essas diferenças. Isso significa que o número de diferenças pode ser enganoso, pois um dispositivo pode ter apenas uma ou duas diferenças, mas elas serem extremamente sérias, e algum outro dispositivo que atualiza o status de registro mais rápido ou mais devagar que a peça de referência (que provavelmente nunca afetaria o operação de um driver devidamente escrito) poderia ter dezenas de diferenças relatadas. O COMTEST pode ser usado como uma ferramenta de triagem para alertar o administrador sobre a presença de componentes potencialmente incompatíveis que podem causar problemas ou que precisam ser tratados como um caso especial. Se você executar o COMTEST em um 16550 que esteja em um modem ou se um modem estiver conectado à porta serial, será necessário primeiro emitir um comando ATE0&W para o modem para que o modem não faça eco de nenhum dos caracteres de teste. Se você esquecer de fazer isso, o COMTEST informará pelo menos essa diferença: [source,shell] .... Error (6)...Timeout interrupt failed: IIR = c1 LSR = 61 .... === Registradores 8250/16450/16550 O UART 8250/16450/16550 ocupa oito endereços contíguos de porta de I/O. No IBM PC, há dois locais definidos para essas oito portas e eles são conhecidos coletivamente como [.filename]#COM1# e [.filename]#COM2#. Os fabricantes de PC-clones e placas adicionais criaram duas áreas adicionais conhecidas como [.filename]#COM3# e [.filename]#COM4#, mas essas portas COM extras entram em conflito com outro hardware em alguns sistemas. O conflito mais comum é com adaptadores de vídeo que fornecem emulação IBM 8514. A [.filename]#COM1# está localizada de 0x3f8 a 0x3ff e normalmente usa o IRQ 4. A [.filename]#COM2# está localizada de 0x2f8 a 0x2ff e normalmente usa IRQ 3. A [.filename]#COM3# está localizada de 0x3e8 a 0x3ef e não tem IRQ padronizado. A [.filename]#COM4# está localizada de 0x2e8 a 0x2ef e não tem IRQ padronizado. Uma descrição das portas I/O da UART 8250/16450/16550 é fornecida abaixo. [.informaltable] [cols="10%,10%,80%", frame="none", options="header"] |=== | Porta I/O | Acesso permitido | Descrição |+0x00 |write (DLAB==0) | Transmit Holding Register (THR). As informações gravadas nessa porta são tratadas como palavras de dados e serão transmitidas pela UART. |+0x00 |read (DLAB==0) | Receive Buffer Register (RBR). Quaisquer palavras de dados recebidas pelo UART a partir do link serial são acessadas pelo host lendo esta porta. |+0x00 |write/read (DLAB==1) | Divisor Latch LSB (DLL) Este valor será dividido a partir do clock de entrada principal (no IBM PC, o clock principal é 1.8432MHz) e o clock resultante determinará a taxa de transmissão do UART. Este registrador contém os bits de 0 a 7 do divisor. |+0x01 |write/read (DLAB==1) | Divisor Latch MSB (DLH) Este valor será dividido a partir do clock de entrada principal (no IBM PC, o clock principal é 1.8432MHz) e o clock resultante determinará a taxa de transmissão do UART. Este registrador contém os bits 8 a 15 do divisor. |+0x01 |write/read (DLAB==0) |Interrupt Enable Register (IER) + A UART 8250/16450/16550 classifica os eventos em uma de quatro categorias. Cada categoria pode ser configurada para gerar uma interrupção quando qualquer um dos eventos ocorrer. A UART 8250/16450/16550 gera um único sinal de interrupção externa, independentemente de quantos eventos nas categorias ativadas ocorreram. Cabe ao processador host responder à interrupção e depois pesquisar as categorias de interrupção ativadas (geralmente todas as categorias têm interrupções ativadas) para determinar a(s) causa(s) verdadeira(s) da interrupção. + Bit 7 -> Reserved, always 0. + Bit 6 -> Reserved, always 0. + Bit 5 -> Reserved, always 0. + Bit 4 -> Reserved, always 0. + Bit 3 -> Ativa o Modem Status Interrupt (EDSSI). Definir esse bit como "1" permite que o UART gere uma interrupção quando ocorrer uma alteração em uma ou mais das linhas de status. + Bit 2 -> Ativa a interrupção de status da linha receptora (ELSI) Configurar este bit como "1" faz com que o UART gere uma interrupção quando um erro (ou um sinal BREAK) for detectado nos dados de entrada. + Bit 1 -> Ativa a Interrupção Vazia do Registro de Holding do Transmissor (ETBEI) Configurar este bit como "1" faz com que o UART gere uma interrupção quando o UART tiver espaço para um ou mais caracteres adicionais que serão transmitidos. + Bit 0 -> Ativar a Interrupção Disponível de Dados Recebidos (ERBFI) Configurar este bit para "1" faz com que o UART gere uma interrupção quando o UART tiver recebido caracteres suficientes para exceder o nível de disparo do FIFO, ou o temporizador FIFO tiver expirado (dados antigos) ou um único caractere tiver sido recebido quando o FIFO está desativado. |+0x02 |write |Registro de Controle FIFO (FCR) (Esta porta não existe no UART 8250 e 16450). + Bit 7 -> Receiver Trigger Bit #1 + Bit 6 -> Trigger do Receptor Bit #0 + Esses dois bits controlam em que ponto o receptor deve gerar uma interrupção quando o FIFO está ativo. + 7 6 Quantas palavras são recebidas antes que uma interrupção seja gerada + 0 0 1 + 0 1 4 + 1 0 8 + 1 1 14 + Bit 5 -> Reserved, always 0. + Bit 4 -> Reserved, always 0. + Bit 3 -> DMA Mode Select. Se o Bit 0 for ajustado para "1" (FIFOs habilitado), a configuração deste bit altera a operação dos sinais -RXRDY e -TXRDY do Modo 0 para o Modo 1. + Bit 2 -> Transmit FIFO Reset. Quando um "1" é gravado neste bit, o conteúdo do FIFO é descartado. Qualquer palavra atualmente sendo transmitida será enviada intacta. Esta função é útil para anular transferências. + Bit 1 -> Receiver FIFO Reset. Quando um "1" é gravado neste bit, o conteúdo do FIFO é descartado. Qualquer palavra atualmente montada no registrador de turno será recebida intacta. + Bit 0 -> 16550 FIFO Enable. Quando configurado, os FIFOs de transmissão e recepção estão ativados. Qualquer conteúdo no registro de espera, registradores de deslocamento ou FIFOs são perdidos quando as FIFOs são ativadas ou desativadas. + |+0x02 |read |Registro de identificação de interrupção + Bit 7 -> FIFOs habilitado. No 8250/16450 UART, esse bit é zero. + Bit 6 -> FIFOs habilitado. No 8250/16450 UART, esse bit é zero. + Bit 5 -> Reserved, always 0. + Bit 4 -> Reserved, always 0. + Bit 3 -> ID de Interrupção Bit #2. No 8250/16450 UART, esse bit é zero. + Bit 2 -> ID de Interrupção Bit #1 + Bit 1 -> ID de Interrupção Bit #0.Esses três bits se combinam para relatar a categoria de evento que causou a interrupção que está em andamento. Essas categorias têm prioridades, portanto, se várias categorias de eventos ocorrerem ao mesmo tempo, a UART relatará os eventos mais importantes primeiro e o host precisará resolver os eventos na ordem em que forem relatados. Todos os eventos que causaram a interrupção atual devem ser resolvidos antes que novas interrupções sejam geradas. (Esta é uma limitação da arquitetura do PC.) + 2 1 0 Prioridade Descrição + 0 1 1 Primeiro Received Error (OE, PE, BI, or FE) + 0 1 0 Segundo Dados Recebidos Disponíveis + 1 1 0 Segundo Identificação do nível de gatilho (dados obsoletos no buffer de recebimento) + 0 0 1 Terceiro Transmissor tem espaço para mais palavras (THRE) + 0 0 0 Quarto Alteração de status do modem (-CTS, -DSR, -RI ou -DCD) + Bit 0 -> Interromper Bit Pendente. Se este bit estiver definido como "0", pelo menos uma interrupção está pendente. |+0x03 |write/read |Registro de Controle de Linha (LCR) + Bit 7 -> Divisor Latch Access Bit (DLAB). Quando configurado, o acesso ao registro de transmissão / recepção de dados (THR / RBR) e ao Registro de Ativação de Interrupção (ITA) é desabilitado. Qualquer acesso a essas portas é agora redirecionado para os Registradores de Latch do Divisor. Definir esse bit, carregar os Registradores do Divisor e limpar o DLAB deve ser feito com as interrupções desativadas. + Bit 6 -> Set Break. Quando definido para "1", o transmissor começa a transmitir espaçamento contínuo até que este bit seja definido como "0". Isso substitui todos os bits de caracteres que estão sendo transmitidos. + Bit 5 -> Paridade da varStick Parity. Quando a paridade está ativada, a configuração desse bit faz com que a paridade seja sempre "1" ou "0", com base no valor do Bit 4. Bit 4 -> Even Parity Select (EPS). Quando a paridade é ativada e o bit 5 é "0", a configuração desse bit faz com que a paridade par seja transmitida e esperada. Caso contrário, a paridade ímpar é usada. + Bit 3 -> Parity Enable (PEN). Quando definido para "1", um bit de paridade é inserido entre o último bit dos dados e o bit de Stop. A UART também espera que a paridade esteja presente nos dados recebidos. + Bit 2 -> Number of Stop Bits (STB). Se definido como "1" e usando palavras de dados de 5 bits, 1.5 bits de parada são transmitidos e esperados em cada palavra de dados. Para palavras de dados de 6, 7 e 8 bits, 2 Stop Bits são transmitidos e esperados. Quando este bit é definido como "0", um bit de parada é usado em cada palavra de dados. + Bit 1 -> Comprimento de palavra selecione bit #1 (WLSB1) + Bit 0 -> Comprimento de palavra selecione bit #0 (WLSB0) + Juntos, esses bits especificam o número de bits em cada palavra de dados. + 1 0 Comprimento da palavra + 0 0 5 bits de dados + 0 1 6 bits de dados + 1 0 7 bits de dados + 1 1 8 bits de dados + |+0x04 |write/read |Registro de Controle de Modem (MCR) + Bit 7 -> Reserved, always 0. + Bit 6 -> Reserved, always 0. + Bit 5 -> Reserved, always 0. + Bit 4 -> Loop-Back Enable. Quando definido para "1", o transmissor e o receptor UART são conectados internamente para permitir operações de diagnóstico. Além disso, as saídas de controle do modem UART são conectadas às entradas de controle do modem UART. O CTS está conectado a RTS, o DTR está conectado a DSR, o OUT1 está conectado a RI e o OUT 2 está conectado a DCD. + Bit 3 -> OUT 2. É uma saída auxiliar que o processador host pode definir como alta ou baixa. No adaptador serial IBM PC (e na maioria dos clones), OUT 2 é usado para triestar (desabilitar) o sinal de interrupção do UART 8250/16450/16550. + Bit 2 -> OUT 1. É uma saída auxiliar que o processador host pode definir como alta ou baixa. Essa saída não é usada no adaptador serial IBM PC. + Bit 1 -> Solicitação para enviar (RTS). Quando definido para "1", a saída da linha UART-RTS é Baixa (Ativo). + Bit 0 -> Data Terminal Ready (DTR). Quando definido para "1", a saída da linha UART-DTR é baixa (ativa). + |+0x05 |write/read |Registro de status de linha (LSR) + Bit 7 -> Error in Receiver FIFO. No UART 8250/16450, esse bit é zero. Esse bit é definido como "1" quando qualquer um dos bytes no FIFO tem uma ou mais das seguintes condições de erro: PE, FE ou BI. + Bit 6 -> Transmitter Empty (TEMT). Quando definido para "1", não há palavras restantes no FIFO de transmissão ou no registrador de deslocamento de transmissão. O transmissor está completamente ocioso. + Bit 5 -> Transmissor Holding Register Empty (THRE). Quando definido para "1", o FIFO (ou registrador de retenção) agora tem espaço para pelo menos uma palavra adicional para transmitir. O transmissor ainda pode estar transmitindo quando este bit está definido para "1". + Bit 4 -> Break Interrupt (BI). O receptor detectou um sinal de Break. + Bit 3 -> Framing Error (FE). Um Bit de Início foi detectado, mas o Bit de Stop não apareceu no horário esperado. A palavra recebida é provavelmente truncada. + Bit 2 -> Parity Error (PE). O bit de paridade estava incorreto para a palavra recebida. + Bit 1 -> Overrun Error (OE). Uma nova palavra foi recebida e não havia espaço no buffer de recebimento. A palavra recém-chegada no registrador de deslocamento é descartada. Nos UARTs 8250/16450, a palavra no registro de retenção é descartada e a palavra recém-chegada é colocada no registro de retenção. + Bit 0 -> Data Ready (DR). Uma ou mais palavras estão no FIFO de recepção que o host pode ler. Uma palavra deve ser completamente recebida e movida do registrador de deslocamento para o FIFO (ou registrador de sustentação para desenhos do 8250/16450) antes que este bit seja definido. |+0x06 |write/read |Registro de status de modem (MSR) + Bit 7 -> Data Carrier Detect (DCD). Reflete o estado da linha DCD no UART. + Bit 6 -> Indicador de anel (RI). Reflete o estado da linha RI no UART. + Bit 5 -> Conjunto de dados pronto (DSR). Reflete o estado da linha DSR no UART. + Bit 4 -> Limpar para enviar (CTS). Reflete o estado da linha CTS no UART. + Bit 3 -> Delta Data Carrier Detect (DDCD). Defina para "1" se a linha -DCD mudou de estado mais uma vez desde a última vez em que o MSR foi lido pelo host. + Bit 2 -> Trailing Edge Ring Indicator (TERI). Defina para "1" se a linha -RI teve uma transição baixa para alta desde a última vez em que o MSR foi lido pelo host. + Bit 1 -> Delta Data Set Ready (DDSR). Defina para "1" se a linha -DSR mudou de estado mais uma vez desde a última vez em que o MSR foi lido pelo host. + Bit 0 -> Delta Clear To Send (DCTS). Defina para "1" se a linha -CTS mudou de estado mais uma vez desde a última vez em que o MSR foi lido pelo host. + |+0x07 |write/read |Scratch Register (SCR). Este registro não executa nenhuma função no UART. Qualquer valor pode ser gravado pelo host para este local e lido pelo host mais tarde. |=== === Além do UART 16550A Embora a National Semiconductor não tenha oferecido nenhum componente compatível com o 16550 que forneça recursos adicionais, vários outros fornecedores oferecem. Alguns desses componentes são descritos abaixo. Deve ser entendido que para utilizar efetivamente essas melhorias, os drivers podem ter que ser fornecidos pelo fornecedor do chip, já que a maioria dos sistemas operacionais populares não suportam recursos além daqueles fornecidos pelo 16550. ST16650:: Por padrão, essa peça é semelhante ao NS16550A, mas um buffer de envio e recebimento de 32 bytes estendido pode ser opcionalmente ativado. Fabricado pela StarTech. TIL16660:: Por padrão, essa peça se comporta de maneira semelhante ao NS16550A, mas um buffer de envio e recebimento de 64 bytes estendido pode ser opcionalmente ativado. Fabricado pela Texas Instruments. Hayes ESP:: Esta placa plug-in proprietária contém um buffer de envio e recebimento de 2048 bytes e suporta taxas de dados de até 230,4 Kbit/s. Fabricada pela Hayes. Além desses UARTs "dumb", muitos fornecedores produzem placas de comunicação serial inteligentes. Esse tipo de design geralmente fornece um microprocessador que faz interface com vários UARTs, processa e armazena os dados em buffer e, em seguida, alerta o processador principal do PC quando necessário. Como os UARTs não são acessados ​​diretamente pelo processador do PC nesse tipo de sistema de comunicação, não é necessário que o fornecedor use UARTs compatíveis com o UART 8250, 16450 ou 16550. Isso deixa o designer livre para usar componentes que tenham melhores características de desempenho. [[sio]] == Configurando o driver [.filename]#sio# O driver [.filename]#sio# fornece suporte para interfaces de comunicação EIA RS-232C (CCITT V.24) baseadas em NS8250-, NS16450-, NS16550 e NS16550A. Várias placas multiportas também são suportadas. Consulte a página de manual man:sio[4] para obter documentação técnica detalhada. === Digi International (DigiBoard) PC/8 _Contribuição de Andrew Webster mailto:awebster@pubnix.net[awebster@pubnix.net]. 26 de agosto de 1995._ Aqui está um trecho de configuração de uma máquina com uma placa Digi International PC/8 com 16550. Ela tem 8 modems conectados a essas 8 linhas e eles funcionam muito bem. Não se esqueça de adicionar `options COM_MULTIPORT` ao seu kernel ou ela não funcionará muito bem! [.programlisting] .... device sio4 at isa? port 0x100 flags 0xb05 device sio5 at isa? port 0x108 flags 0xb05 device sio6 at isa? port 0x110 flags 0xb05 device sio7 at isa? port 0x118 flags 0xb05 device sio8 at isa? port 0x120 flags 0xb05 device sio9 at isa? port 0x128 flags 0xb05 device sio10 at isa? port 0x130 flags 0xb05 device sio11 at isa? port 0x138 flags 0xb05 irq 9 .... O truque para configurá-la é que o MSB dos flags representa a última porta SIO, neste caso 11, então as flags são 0xb05. === Boca 16 _Contribuição de Don Whiteside mailto:whiteside@acm.org[whiteside@acm.org]. 26 de agosto de 1995._ Os procedimentos para fazer uma placa multiporta Boca 16 funcionar com o FreeBSD são bastante diretos, mas você precisará de algumas coisas para fazê-la funcionar: . Você precisa do código fonte do kernel instalado para poder recompilar as opções necessárias ou precisará de alguém para compilá-las para você. O kernel padrão 2.0.5 _não_ vem com suporte a múltiplas portas ativado e você precisará adicionar uma entrada de dispositivo para cada porta de qualquer maneira. . Dois, você precisará saber a configuração de interrupção e de I/O da sua placa Boca para que você possa definir essas opções corretamente no kernel. Uma nota importante - os chips UART reais para a Boca 16 estão nos conectores, não na própria placa interna. Então, se você os tiver desconectado, os probes destas portas falharão. Eu nunca testei a inicialização com a caixa desconectada e conectando-a novamente, e sugiro que você também não o faça. Se você ainda não tiver um arquivo de configuração de kernel personalizado, consulte o capitulo link:{handbook}kernelconfig/[Configuração do Kernel] no Handbook do FreeBSD para os procedimentos gerais. A seguir estão as especificações para a placa Boca 16 e supõe-se que você esteja usando o nome do kernel MYKERNEL e editando com o vi. [.procedure] . Adicione a linha + [.programlisting] .... options COM_MULTIPORT .... ao arquivo de configuração. . Onde as linhas atuais do dispositivo `device sio__n__` estão, você precisará adicionar mais 16 dispositivos. O exemplo a seguir é para uma placa Boca com uma interrupção de 3 e um endereço de IO base de 100h. O endereço IO para cada porta é +8 hexadecimal da porta anterior, portanto, os endereços são 100h, 108h, 110h .... + [.programlisting] .... device sio1 at isa? port 0x100 flags 0x1005 device sio2 at isa? port 0x108 flags 0x1005 device sio3 at isa? port 0x110 flags 0x1005 device sio4 at isa? port 0x118 flags 0x1005 … device sio15 at isa? port 0x170 flags 0x1005 device sio16 at isa? port 0x178 flags 0x1005 irq 3 .... + A entrada de flags _deve_ ser alterada deste exemplo, a menos que você esteja usando exatamente as mesmas atribuições de sio. As sinalizações são definidas de acordo com 0x``__MYY__`` onde _M_ indica o número menor da porta principal (a última porta em uma Boca 16) e _YY_ indica se o FIFO está ativado ou desativado (ativado), o compartilhamento de IRQ é usado (sim) e se há um registro de controle de IRQ compatível com AST/4 (não). Neste exemplo, + [.programlisting] .... flags 0x1005 .... indica que a porta principal é a sio16. Se eu adicionasse outra placa e atribuísse do sio17 até sio28, os sinalizadores para todas as 16 portas _nesta_ placa seriam 0x1C05, onde 1C indica o menor número da porta principal. Não altere a configuração 05. . Salve e complete a configuração do kernel, recompile, instale e reinicialize. Presumindo que você tenha instalado com sucesso o kernel recompilado e configurado para o endereço e IRQ correto, sua mensagem de boot deve indicar o teste bem-sucedido das portas Boca da seguinte forma: (obviamente os números sio, IO e IRQ podem ser diferentes) + [source,shell] .... sio1 at 0x100-0x107 flags 0x1005 on isa sio1: type 16550A (multiport) sio2 at 0x108-0x10f flags 0x1005 on isa sio2: type 16550A (multiport) sio3 at 0x110-0x117 flags 0x1005 on isa sio3: type 16550A (multiport) sio4 at 0x118-0x11f flags 0x1005 on isa sio4: type 16550A (multiport) sio5 at 0x120-0x127 flags 0x1005 on isa sio5: type 16550A (multiport) sio6 at 0x128-0x12f flags 0x1005 on isa sio6: type 16550A (multiport) sio7 at 0x130-0x137 flags 0x1005 on isa sio7: type 16550A (multiport) sio8 at 0x138-0x13f flags 0x1005 on isa sio8: type 16550A (multiport) sio9 at 0x140-0x147 flags 0x1005 on isa sio9: type 16550A (multiport) sio10 at 0x148-0x14f flags 0x1005 on isa sio10: type 16550A (multiport) sio11 at 0x150-0x157 flags 0x1005 on isa sio11: type 16550A (multiport) sio12 at 0x158-0x15f flags 0x1005 on isa sio12: type 16550A (multiport) sio13 at 0x160-0x167 flags 0x1005 on isa sio13: type 16550A (multiport) sio14 at 0x168-0x16f flags 0x1005 on isa sio14: type 16550A (multiport) sio15 at 0x170-0x177 flags 0x1005 on isa sio15: type 16550A (multiport) sio16 at 0x178-0x17f irq 3 flags 0x1005 on isa sio16: type 16550A (multiport master) .... + Se as mensagens forem muito rápidas para serem visualizadas, + [source,shell] .... # dmesg | more .... + mostrará as mensagens de inicialização. . Em seguida, as entradas apropriadas em [.filename]#/dev# para os dispositivos devem ser criadas usando o script [.filename]#/dev/MAKEDEV#. Esta etapa pode ser omitida se você estiver executando o FreeBSD 5.X com um kernel que tenha sido compilado com o suporte ao man:devfs[5]. + Se você precisar criar as entradas [.filename]#/dev#, execute o seguinte como `root`: + [source,shell] .... # cd /dev # ./MAKEDEV tty1 # ./MAKEDEV cua1 (everything in between) # ./MAKEDEV ttyg # ./MAKEDEV cuag .... + Se você não quiser ou precisar de dispositivos de chamada por algum motivo, você pode dispensar o uso dos dispositivos [.filename]#cua*#. . Se você quiser uma maneira rápida e desleixada de se certificar de que os dispositivos estão funcionando, você pode simplesmente conectar um modem em cada porta e (como root) + [source,shell] .... # echo at > ttyd* .... + para cada dispositivo que você fez. Você _deve_ ver as luzes RX piscando para cada porta em funcionamento. === Suporte para cartões Multi-UART baratos _Contribuição de Helge Oldach mailto:hmo@sep.hamburg.com[hmo@sep.hamburg.com], setembro de 1999_ Já se perguntou se o FreeBSD suporta a sua placa multi-I/O de US$ 20 com duas (ou mais) portas COM, compartilhando IRQs? Aqui está como: Normalmente, a única opção para suportar esse tipo de placa é usar um IRQ distinto para cada porta. Por exemplo, se a placa da CPU tiver uma porta [.filename]#COM1# integrada (também conhecida como [.filename]#sio0# - endereço de I/O 0x3F8 e IRQ 4) e você tiver uma placa de extensão com dois UARTs , você normalmente precisará configurá-los como [.filename]#COM2# (também conhecido como [.filename]#sio1# - endereço de I/O 0x2F8 e IRQ 3) e a terceira porta (também conhecida como [.filename]#sio2#) como I/O 0x3E8 e IRQ 5. Obviamente, isso é um desperdício de recursos de IRQ, já que deve ser basicamente possível executar ambas as portas da placa de extensão usando um único IRQ com a configuração `COM_MULTIPORT` descrita nas seções anteriores. Essas placas de I/O baratas geralmente têm uma matriz de jumpers de 4 por 3 para as portas COM, semelhante à seguinte: [.programlisting] .... o o o * Port A | o * o * Port B | o * o o IRQ 2 3 4 5 .... É mostrada aqui a porta A com fiação para IRQ 5 e a porta B com fiação para IRQ 3. As colunas de IRQ em sua placa específica podem variar - outras placas podem fornecer jumpers para IRQs 3, 4, 5 e 7. Pode-se concluir que a fiação de ambas as portas para o IRQ 3 usando um jumper feito a mão e feito à mão cobrindo todos os três pontos de conexão na coluna IRQ 3 resolveria o problema, mas não. Você não pode duplicar o IRQ 3 porque os drivers de saída de cada UART estão conectados de forma "totem pole", portanto, se um dos UARTs ativar o IRQ 3, o sinal de saída não será o esperado. Dependendo da implementação da placa de extensão ou da placa-mãe, a linha IRQ 3 permanecerá sempre ativa ou sempre baixa. Você precisa separar os drivers de IRQ para as duas UARTs, de modo que a linha IRQ da placa só suba se (e somente se) uma das UARTs ativar uma IRQ e permanecendo abaixo de outra forma. A solução foi proposta por Joerg Wunsch mailto:j@ida.interface-business.de[j@ida.interface-business.de]: Soldar um cabo - ou consistindo de dois diodos (de Germânio ou do tipo-Schottky são fortemente preferidos) e um resistor de 1 kOhm. Aqui está o esquema, a partir do campo de jumper 4 por 3 acima: [.programlisting] .... Diode +---------->|-------+ / | o * o o | 1 kOhm Port A +----|######|-------+ o * o o | | Port B `-------------------+ ==+== o * o o | Ground \ | +--------->|-------+ IRQ 2 3 4 5 Diode .... Os cátodos dos diodos estão conectados a um ponto comum, junto com um resistor de 1 kOhm. É essencial conectar o resistor ao terra para evitar a flutuação da linha IRQ no barramento. Agora estamos prontos para configurar um kernel. Ficando com este exemplo, nós configuraríamos: [.programlisting] .... # standard on-board COM1 port device sio0 at isa? port "IO_COM1" flags 0x10 # patched-up multi-I/O extension board options COM_MULTIPORT device sio1 at isa? port "IO_COM2" flags 0x205 device sio2 at isa? port "IO_COM3" flags 0x205 irq 3 .... Note que a configuração das `flags` para [.filename]#sio1# e [.filename]#sio2# é realmente essencial; consulte man:sio[4] para detalhes. (Geralmente, o `2` no atributo "flags" refere-se ao [.filename]#sio2# que contém o IRQ, e você certamente deseja um "nibble" abaixo de `5`. ) Com o modo verboso do kernel ativado, isso deve render algo semelhante a isto: [source,shell] .... sio0: irq maps: 0x1 0x11 0x1 0x1 sio0 at 0x3f8-0x3ff irq 4 flags 0x10 on isa sio0: type 16550A sio1: irq maps: 0x1 0x9 0x1 0x1 sio1 at 0x2f8-0x2ff flags 0x205 on isa sio1: type 16550A (multiport) sio2: irq maps: 0x1 0x9 0x1 0x1 sio2 at 0x3e8-0x3ef irq 3 flags 0x205 on isa sio2: type 16550A (multiport master) .... Embora o [.filename]#/sys/i386/isa/sio.c# seja um pouco enigmático com o uso do array "irq maps" acima, a ideia básica é que você observe `0x1` no primeiro, terceiro e quarto lugar. Isso significa que o IRQ correspondente foi definido na saída e limpo depois, o que é exatamente o que esperaríamos. Se o seu kernel não exibir esse comportamento, provavelmente há algo errado com a sua fiação. [[cy]] == Configurando o driver [.filename]#cy# _Contribuição de Alex Nash. 6 de Junho de 1996._ As placas multiseriais da Cyclades são baseadas no driver [.filename]#cy# em vez do driver usual [.filename]#sio# usado por outras placas multiseriais. Configuração é uma simples questão de: [.procedure] . Adicione o dispositivo [.filename]#cy# à sua configuração do kernel (observe que suas configurações irq e iomem podem ser diferentes). + [.programlisting] .... device cy0 at isa? irq 10 iomem 0xd4000 iosiz 0x2000 .... . Recompile e instale o novo kernel. . Crie os device nodes digitando (o exemplo a seguir assume uma placa de 8 portas) footnote:[Você pode omitir esta parte se você estiver executando o FreeBSD 5.X com devfs5.]: + [source,shell] .... # cd /dev # for i in 0 1 2 3 4 5 6 7;do ./MAKEDEV cuac$i ttyc$i;done .... . Se apropriado, adicione entradas de discagem ao [.filename]#/etc/ttys# duplicando as entradas dos dispositivos seriais (`ttyd`) e usando `ttyc` no lugar de `ttyd`. Por exemplo: + [.programlisting] .... ttyc0 "/usr/libexec/getty std.38400" unknown on insecure ttyc1 "/usr/libexec/getty std.38400" unknown on insecure ttyc2 "/usr/libexec/getty std.38400" unknown on insecure … ttyc7 "/usr/libexec/getty std.38400" unknown on insecure .... . Reinicie com o novo kernel. == Configurando o driver [.filename]#si# _Contribuição de Nick Sayer mailto:nsayer@FreeBSD.org[nsayer@FreeBSD.org]. 25 de Março de 1998._ As placas multiportas Specialix SI/XIO e SX usam o driver [.filename]#si#. Uma única máquina pode ter até 4 placas host. As seguintes placas host são suportadas: * ISA SI/XIO host card (2 versions) * EISA SI/XIO host card * PCI SI/XIO host card * ISA SX host card * PCI SX host card Embora as placas host SX e SI/XIO pareçam marcadamente diferentes, sua funcionalidade é basicamente a mesma. Os cartões de host não usam locais de I/O, mas exigem um bloco de memória de 32K. A configuração de fábrica para cartões ISA coloca isso em `0xd0000-0xd7fff`. Elas também exigem um IRQ. As placas PCI, é claro, se configuram automaticamente. Você pode anexar até 4 módulos externos a cada placa de host. Os módulos externos contêm 4 ou 8 portas seriais. Eles vêm nas seguintes variedades: * Módulos de portas SI 4 ou 8. Até 57600 bps em cada porta suportada. * Módulos de porta XIO 8. Até 115.200 bps em cada porta suportada. Um tipo de módulo XIO possui 7 portas seriais e 1 porta paralela. * Módulos de porta SXDC 8. Até 921.600 bps em cada porta suportada. Tal como no XIO, um módulo está disponível com uma porta paralela também. Para configurar uma placa de host ISA, adicione a seguinte linha ao seu arquivo de configuração do kernel, alterando os números conforme apropriado: [.programlisting] .... device si0 at isa? iomem 0xd0000 irq 11 .... Números de IRQ válidos são 9, 10, 11, 12 e 15 para placas host SX ISA e 11, 12 e 15 para placas host ISA/XIO ISA. Para configurar uma placa de host EISA ou PCI, use esta linha: [.programlisting] .... device si0 .... Depois de adicionar a entrada de configuração, recompile e instale seu novo kernel. [NOTE] ==== A etapa seguinte, não é necessária se você estiver usando o man:devfs[5] no FreeBSD 5._X_. ==== Após a reinicialização com o novo kernel, você precisa criar os device nodes no [.filename]#/dev#. O script [.filename]#MAKEDEV# cuidará disso para você. Conte quantas portas totais você tem e digite: [source,shell] .... # cd /dev # ./MAKEDEV ttyAnn cuaAnn .... (no qual _nn_ é o número de portas) Se você quiser que as solicitações de login apareçam nessas portas, você precisará adicionar linhas como esta para [.filename]#/etc/ttys#: [.programlisting] .... ttyA01 "/usr/libexec/getty std.9600" vt100 on insecure .... Altere o tipo de terminal conforme apropriado. Para modems, `dialup` ou `unknown` está bem. diff --git a/documentation/content/pt-br/articles/vinum/_index.adoc b/documentation/content/pt-br/articles/vinum/_index.adoc index 40d20eaacf..a1ee01695a 100644 --- a/documentation/content/pt-br/articles/vinum/_index.adoc +++ b/documentation/content/pt-br/articles/vinum/_index.adoc @@ -1,578 +1,579 @@ --- title: O Gerenciador de Volume vinum authors: - author: Greg Lehey --- = O Gerenciador de Volume vinum :doctype: article :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :toc-title: Índice :part-signifier: Parte :chapter-signifier: Capítulo :appendix-caption: Apêndice :table-caption: Tabela :figure-caption: Figura :example-caption: Exemplo -include::shared/pt-br/urls.adoc[] - ifeval::["{backend}" == "html5"] +include::shared/pt-br/urls.adoc[] :imagesdir: ../../../images/articles/vinum/ endif::[] ifeval::["{backend}" == "pdf"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/vinum/ endif::[] ifeval::["{backend}" == "epub3"] +include::../../../../shared/pt-br/urls.adoc[] :imagesdir: ../../../../static/images/articles/vinum/ endif::[] ''' toc::[] [[vinum-synopsis]] == Sinopse Não importa o tipo de disco, sempre há problemas em potencial. Os discos podem ser muito pequenos, muito lentos ou pouco confiáveis para atender aos requisitos do sistema. Enquanto os discos estão ficando maiores, também ficam maiores os requisitos para armazenamento de dados. Geralmente, é necessário um sistema de arquivos maior que a capacidade de um disco. Várias soluções para esses problemas foram propostas e implementadas. Um método é através do uso de vários discos, e às vezes discos redundantes. Além de suportar várias placas e controladoras para sistemas `RAID` (Redundant Array of Independent Disks), o sistema básico do FreeBSD inclui o gerenciador de volumes [.filename]#vinum#, um driver de dispositivo de bloco que implementa discos virtuais e aborda esses três problemas. O [.filename]#vinum# oferece mais flexibilidade, desempenho e confiabilidade do que o armazenamento em disco tradicional e implementa os modelos `RAID`-0, `RAID`-1 e `RAID`-5, tanto individualmente quanto combinados. Este capítulo fornece uma visão geral dos possíveis problemas com o armazenamento em disco tradicional e uma introdução ao gerenciador de volumes [.filename]#vinum#. [NOTE] ==== Começando com o FreeBSD 5, o [.filename]#vinum# foi reescrito para se encaixar na link:{handbook}#geom[Arquitetura GEOM], mantendo as idéias originais, a terminologia e os metadados no disco. Esta reescrita é chamada _gvinum_ (para _GEOM vinum_). Enquanto este capítulo usa o termo [.filename]#vinum#, qualquer invocação de comandos deve ser executada com o `gvinum`. O nome do módulo do kernel mudou do original [.filename]#vinum.ko# para [.filename]#geom_vinum.ko#, e todos os device nodes residem em [.filename]#/dev/gvinum# em vez de [.filename]#/dev/vinum#. A partir do FreeBSD 6, a implementação original do [.filename]#vinum# não está mais disponível no código base. ==== [[vinum-access-bottlenecks]] == Gargalos de Acesso Sistemas modernos frequentemente precisam acessar dados de uma maneira altamente concorrente. Por exemplo, grandes servidores FTP ou HTTP podem manter milhares de sessões simultâneas e ter múltiplas conexões de 100 Mbit/s para o mundo externo, muito além da taxa de transferência sustentada da maioria dos discos. As unidades de disco atuais podem transferir dados sequencialmente a até 70 MB/s, mas esse valor é de pouca importância em um ambiente em que muitos processos independentes acessam uma unidade e onde podem obter apenas uma fração desses valores. Nesses casos, é mais interessante visualizar o problema do ponto de vista do subsistema de disco. O parâmetro importante é a carga que uma transferência coloca no subsistema ou o tempo pelo qual uma transferência ocupa as unidades envolvidas na transferência. Em qualquer transferência de disco, a unidade deve primeiro posicionar as cabeças, aguardar que o primeiro setor passe sob a cabeça de leitura e depois realizar a transferência. Essas ações podem ser consideradas atômicas, pois não faz sentido interrompê-las. [[vinum-latency]] Considere uma transferência típica de cerca de 10 kB: a geração atual de discos de alto desempenho pode posicionar as cabeças em uma média de 3,5 ms. As unidades mais rápidas giram a 15.000 rpm, portanto a latência rotacional média (meia revolução) é de 2 ms. A 70 MB/s, a própria transferência leva cerca de 150 μs, quase nada em comparação com o tempo de posicionamento. Nesse caso, a taxa de transferência efetiva cai para pouco mais de 1 MB/s e é claramente altamente dependente do tamanho da transferência. A solução tradicional e óbvia para esse gargalo é "mais eixos": em vez de usar um disco grande, use vários discos menores com o mesmo espaço de armazenamento agregado. Cada disco é capaz de se posicionar e transferir de forma independente, portanto, o rendimento efetivo aumenta em um fator próximo ao número de discos usados. A melhoria real da taxa de transferência é menor que o número de discos envolvidos. Embora cada unidade seja capaz de transferir em paralelo, não há como garantir que as solicitações sejam distribuídas uniformemente pelas unidades. Inevitavelmente, a carga em uma unidade será maior que em outra. A uniformidade da carga nos discos é fortemente dependente da maneira como os dados são compartilhados entre as unidades. Na discussão a seguir, é conveniente pensar no armazenamento em disco como um grande número de setores de dados que são endereçáveis por número, mais ou menos como as páginas de um livro. O método mais óbvio é dividir o disco virtual em grupos de setores consecutivos do tamanho dos discos físicos individuais e armazená-los dessa maneira, mais ou menos como pegar um livro grande e dividi-lo em seções menores. Esse método é chamado de _concatenação_ e tem a vantagem de os discos não precisarem ter nenhum relacionamento de tamanho específico. Ele funciona bem quando o acesso ao disco virtual é distribuído uniformemente sobre seu espaço de endereço. Quando o acesso é concentrado em uma área menor, a melhoria é menos acentuada. <> ilustra a seqüência na qual as unidades de armazenamento são alocadas em uma organização concatenada. [[vinum-concat]] .Organização Concatenada image::vinum-concat.png[] Um mapeamento alternativo é dividir o espaço de endereço em componentes menores e de tamanhos iguais e armazená-los sequencialmente em diferentes dispositivos. Por exemplo, os primeiros 256 setores podem ser armazenados no primeiro disco, os próximos 256 setores no próximo disco e assim por diante. Depois de preencher o último disco, o processo é repetido até que os discos estejam cheios. Este mapeamento é chamado _striping_ ou RAID-0. O `RAID` oferece várias formas de tolerância a falhas, embora o RAID-0 seja um pouco enganador, pois não fornece redundância. O striping requer um pouco mais de esforço para localizar os dados e pode causar carga de I/O (INPUT/OUTPUT) adicional, onde uma transferência é distribuída por vários discos, mas também pode fornecer uma carga mais constante nos discos. <> ilustra a seqüência na qual as unidades de armazenamento são alocadas em uma organização distribuída. [[vinum-striped]] .Organização do modo distribuido (Striped) image::vinum-striped.png[] [[vinum-data-integrity]] == Integridade de dados O problema final com os discos é que eles não são confiáveis. Embora a confiabilidade tenha aumentado tremendamente nos últimos anos, as unidades de disco ainda são o componente central mais provável de um servidor para falhar. Quando o fazem, os resultados podem ser catastróficos e substituir uma unidade de disco com falha e a restauração de dados pode resultar em tempo de inatividade do servidor. Uma abordagem para esse problema é o _mirroring (espelhamento)_, ou RAID-1, que mantém duas cópias dos dados em diferentes hardwares físicos. Qualquer gravação no volume grava em ambos os discos; uma leitura pode ser satisfeita de qualquer um, portanto, se uma unidade falhar, os dados ainda estarão disponíveis na outra unidade. O mirroring tem dois problemas: * Requer o dobro de armazenamento em disco que uma solução não redundante. * As gravações devem ser executadas em ambas as unidades, então ela usa o dobro da largura de banda de um volume não espelhado. As leituras não sofrem uma penalidade de desempenho e podem até ser mais rápidas. Uma solução alternativa é a _parity (paridade)_, implementada nos níveis `RAID` 2, 3, 4 e 5. Destes, o RAID-5 é o mais interessante. Como implementado no [.filename]#vinum#, é uma variante em uma organização striped que dedica um bloco de cada distribuição à paridade de um dos outros blocos. Como implementado por [.filename]#vinum#, um plex RAID-5 é semelhante a um plex striped, exceto que ele implementa RAID-5 incluindo um bloco de paridade em cada stripe. Conforme exigido pelo RAID-5, o local desse bloco de paridade muda de um stripe para o próximo. Os números nos blocos de dados indicam os números de blocos relativos. [[vinum-raid5-org]] .Organização `RAID`-5 image::vinum-raid5-org.png[] Comparado ao mirroring, o RAID-5 tem a vantagem de exigir significativamente menos espaço de armazenamento. O acesso de leitura é semelhante ao das organizações distribuídas, mas o acesso de gravação é significativamente mais lento, aproximadamente 25% do desempenho de leitura. Se uma unidade falhar, a matriz pode continuar a operar no modo degradado, onde uma leitura de uma das unidades acessíveis restantes continua normalmente, mas uma leitura da unidade com falha é recalculada a partir do bloco correspondente de todas as unidades restantes. [[vinum-objects]] == Objetos do [.filename]#vinum# A fim de resolver estes problemas, o [.filename]#vinum# implementa uma hierarquia de quatro níveis de objetos: * O objeto mais visível é o disco virtual, chamado _volume_. Os volumes têm essencialmente as mesmas propriedades de uma unidade de disco UNIX(R), embora haja algumas pequenas diferenças. Por um lado, eles não têm limitações de tamanho. * Os volumes são compostos de _plexes_, cada um dos quais representa o espaço de endereço total de um volume. Este nível na hierarquia fornece redundância. Pense em plexes como discos individuais em uma matriz espelhada, cada um contendo os mesmos dados. * Como o [.filename]#vinum# existe dentro do framework de armazenamento em disco UNIX(R), seria possível usar as partições UNIX(R) como bloco de construção para plexes de vários discos. Na verdade, isso acaba sendo muito inflexível, pois os discos UNIX(R) podem ter apenas um número limitado de partições. Em vez disso, o [.filename]#vinum# subdivide uma única partição UNIX(R), a _unidade_, em áreas contíguas chamadas _subdiscos_ , que são usados como blocos de construção para plexes. * Subdiscos residem em [.filename]#vinum# _drives_, atualmente partições UNIX(R). Unidades [.filename]#vinum# podem conter qualquer número de subdiscos. Com exceção de uma pequena área no início da unidade, que é usada para armazenar informações de configuração e estado, a unidade inteira está disponível para armazenamento de dados. As seções a seguir descrevem a maneira como esses objetos fornecem a funcionalidade necessária do [.filename]#vinum#. === Considerações sobre o tamanho do volume Os plexes podem incluir vários subdiscos distribuídos por todas as unidades na configuração [.filename]#vinum#. Como resultado, o tamanho de uma unidade individual não limita o tamanho de um plex ou de um volume. === Armazenamento de Dados Redundantes O [.filename]#vinum# implementa o espelhamento anexando vários plexes a um volume. Cada plex é uma representação dos dados em um volume. Um volume pode conter entre um e oito plexes. Embora um plex represente os dados completos de um volume, é possível que partes da representação estejam fisicamente ausentes, seja por design (por não definir um subdisco para partes do plex) ou por acidente (como resultado da falha de representação). Contanto que pelo menos um plex possa fornecer os dados para o intervalo de endereços completo do volume, o volume estará totalmente funcional. === Quais são as organizações disponíveis para um Plex? O [.filename]#vinum# implementa a concatenação e o striping no nível plex: * Um _plex concatenado_ usa o espaço de endereço de cada subdisco um de cada vez. Plexes concatenados são os mais flexíveis, pois podem conter qualquer número de subdiscos e os subdiscos podem ser de tamanho diferente. O plex pode ser estendido adicionando subdiscos adicionais. Eles exigem menos tempo de CPU do que os plexes distribuídos, embora a diferença na sobrecarga de CPU não seja mensurável. Por outro lado, eles são mais suscetíveis a hot spots, nos quais um disco é muito ativo e outros ficam ociosos. * Um _plex striped_ distribui os dados uniformemente entre cada subdisco. Os subdiscos devem ser todos do mesmo tamanho e deve haver pelo menos dois subdiscos para distingui-los de um plex concatenado. A maior vantagem dos plexes striped é que eles reduzem os hot spots. Ao escolher uma faixa de tamanho ideal, de cerca de 256 kB, a carga pode ser nivelada nas unidades de componentes. Estender um complexo adicionando novos subdiscos é algo tão complicado que o [.filename]#vinum# não o implementa. <> resume as vantagens e desvantagens de cada organização plex. [[vinum-comparison]] .Organizações Plex do [.filename]#vinum# [cols="1,1,1,1,1", frame="none", options="header"] |=== | Tipo plex | Subdiscos mínimos | Pode adicionar subdiscos | Deve ser de tamanho igual | Aplicação |concatenado |1 |sim |não |Armazenamento de dados grandes com flexibilidade máxima de posicionamento e desempenho moderado |striped |2 |não |sim |Alto desempenho em combinação com acesso altamente concorrente |=== [[vinum-examples]] == Alguns exemplos O [.filename]#vinum# mantém um _banco de dados de configuração_ que descreve os objetos conhecidos de um sistema individual. Inicialmente, o usuário cria o banco de dados de configuração a partir de um ou mais arquivos de configuração usando man:gvinum[8]. O [.filename]#vinum# armazena uma cópia de seu banco de dados de configuração em cada _dispositivo_ de disco sob seu controle. Este banco de dados é atualizado em cada mudança de estado, de modo que uma reinicialização restaura com precisão o estado de cada objeto [.filename]#vinum#. === O arquivo de configuração O arquivo de configuração descreve objetos [.filename]#vinum# individuais. A definição de um volume simples pode ser: [.programlisting] .... drive a device /dev/da3h volume myvol plex org concat sd length 512m drive a .... Este arquivo descreve quatro objetos [.filename]#vinum#: * A linha _drive_ descreve uma partição de disco (_drive_) e sua localização relativa ao hardware subjacente. É dado o nome simbólico _a_. Essa separação de nomes simbólicos de nomes de dispositivos permite que os discos sejam movidos de um local para outro sem confusão. * A linha _volume_ descreve um volume. O único atributo obrigatório é o nome, neste caso _myvol_. * A linha _plex_ define um plex. O único parâmetro requerido é a organização, neste caso _concat_. Nenhum nome é necessário, pois o sistema gera automaticamente um nome a partir do nome do volume, adicionando o sufixo _.px_, onde _x_ é o número de o plex no volume. Assim, este plex será chamado _myvol.p0_. * A linha _sd_ descreve um subdisco. As especificações mínimas são o nome de uma unidade na qual irá armazená-lo e o tamanho do subdisco. Nenhum nome é necessário porque o sistema atribui automaticamente nomes derivados do nome do plex adicionando o sufixo _.sx_, onde _x_ é o número do subdisco no plex. Assim, [.filename]#vinum# dá ao subdisco o nome _myvol.p0.s0_. Depois de processar este arquivo, o man:gvinum[8] produz a seguinte saída: [.programlisting] .... # gvinum -> create config1 Configuration summary Drives: 1 (4 configured) Volumes: 1 (4 configured) Plexes: 1 (8 configured) Subdisks: 1 (16 configured) D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%) V myvol State: up Plexes: 1 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB .... Esta saída mostra o formato de listagem breve de man:gvinum[8]. Ele está representado graficamente em <>. [[vinum-simple-vol]] .Um volume [.filename]#vinum# simples image::vinum-simple-vol.png[] Esta figura, e as que se seguem, representam um volume, que contém os plexes, que por sua vez contém os subdiscos. Neste exemplo, o volume contém um plex e o plex contém um subdisco. Este volume específico não tem nenhuma vantagem específica sobre uma partição de disco convencional. Ele contém um único plex, por isso não é redundante. O plex contém um único subdisco, portanto, não há diferença na alocação de armazenamento de uma partição de disco convencional. As seções a seguir ilustram vários métodos de configuração mais interessantes. === Maior Resiliência: Espelhamento A resiliência de um volume pode ser aumentada pelo espelhamento. Ao dispor um volume espelhado, é importante garantir que os subdiscos de cada plex estejam em unidades diferentes, de modo que uma falha no dispositivo não derrubará os dois plexes. A configuração a seguir espelha um volume: [.programlisting] .... drive b device /dev/da4h volume mirror plex org concat sd length 512m drive a plex org concat sd length 512m drive b .... Neste exemplo, não foi necessário especificar uma definição de drive _a_ novamente, já que o [.filename]#vinum# registra todos os objetos em seu banco de dados de configuração. Depois de processar esta definição, a configuração se parece com: [.programlisting] .... Drives: 2 (4 configured) Volumes: 2 (4 configured) Plexes: 3 (8 configured) Subdisks: 3 (16 configured) D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%) D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%) V myvol State: up Plexes: 1 Size: 512 MB V mirror State: up Plexes: 2 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB .... <> mostra a estrutura graficamente. [[vinum-mirrored-vol]] .Um volume [.filename]#vinum# espelhado image::vinum-mirrored-vol.png[] Neste exemplo, cada plex contém os 512 MB completos do espaço de endereço. Como no exemplo anterior, cada plex contém apenas um único subdisco. === Otimizando o desempenho O volume espelhado no exemplo anterior é mais resistente a falhas do que um volume não espelhado, mas seu desempenho é menor, pois cada gravação no volume requer uma gravação nas duas unidades, utilizando uma grande parte da largura de banda total do disco. As considerações de desempenho exigem uma abordagem diferente: em vez de espelhar, os dados são distribuídos em quantas unidades de disco forem possíveis. A configuração a seguir mostra um volume com um plex distribuído em quatro unidades de disco: [.programlisting] .... drive c device /dev/da5h drive d device /dev/da6h volume stripe plex org striped 512k sd length 128m drive a sd length 128m drive b sd length 128m drive c sd length 128m drive d .... Como antes, não é necessário definir as unidades que já são conhecidas por [.filename]#vinum#. Depois de processar esta definição, a configuração se parece com: [.programlisting] .... Drives: 4 (4 configured) Volumes: 3 (4 configured) Plexes: 4 (8 configured) Subdisks: 7 (16 configured) D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%) D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%) D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%) D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%) V myvol State: up Plexes: 1 Size: 512 MB V mirror State: up Plexes: 2 Size: 512 MB V striped State: up Plexes: 1 Size: 512 MB P myvol.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p0 C State: up Subdisks: 1 Size: 512 MB P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB P striped.p1 State: up Subdisks: 1 Size: 512 MB S myvol.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p0.s0 State: up PO: 0 B Size: 512 MB S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB S striped.p0.s0 State: up PO: 0 B Size: 128 MB S striped.p0.s1 State: up PO: 512 kB Size: 128 MB S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB .... [[vinum-striped-vol]] .Um volume [.filename]#vinum# concatenado image::vinum-striped-vol.png[] Este volume é representado em <>. A escuridão das strips indica a posição dentro do espaço de endereço plex, onde as faixas mais claras vêm primeiro e as mais escuras por último. === Resiliência e Desempenho [[vinum-resilience]] Com hardware suficiente, é possível construir volumes que mostrem maior resiliência e melhor desempenho em comparação com as partições padrão UNIX(R). Um arquivo de configuração típico pode ser: [.programlisting] .... volume raid10 plex org striped 512k sd length 102480k drive a sd length 102480k drive b sd length 102480k drive c sd length 102480k drive d sd length 102480k drive e plex org striped 512k sd length 102480k drive c sd length 102480k drive d sd length 102480k drive e sd length 102480k drive a sd length 102480k drive b .... Os subdiscos do segundo plex são compensados por duas unidades daquelas do primeiro plex. Isso ajuda a garantir que as gravações não vão para os mesmos subdiscos, mesmo que uma transferência passe por duas unidades. <> representa a estrutura deste volume. [[vinum-raid10-vol]] .Um volume [.filename]#vinum# espelhado e concatenado image::vinum-raid10-vol.png[] [[vinum-object-naming]] == Nomeação de Objetos O [.filename]#vinum# atribui nomes padrões a plexes e subdiscos, embora eles possam ser substituídos. Substituir os nomes padrões não é recomendado, pois não isso traz nenhuma vantagem significativa e pode causar confusão. Os nomes podem conter qualquer caractere não-branco, mas é recomendado restringi-los a letras, dígitos e caracteres de sublinhado. Os nomes de volumes, plexes e subdiscos podem ter até 64 caracteres e os nomes das unidades podem ter até 32 caracteres. Os objetos [.filename]#vinum# são designados a device nodes na hierarquia [.filename]#/dev/gvinum#. A configuração mostrada acima faria com que o [.filename]#vinum# criasse os seguintes device nodes: * Entradas de dispositivos para cada volume. Estes são os principais dispositivos usados pelo [.filename]#vinum#. A configuração acima incluiria os dispositivos [.filename]#/dev/gvinum/myvol#, [.filename]#/dev/gvinum/mirror#, [.filename]#/dev/gvinum/striped#, [.filename]#/dev/gvinum/raid5# e o [.filename]#/dev/gvinum/raid10#. * Todos os volumes recebem entradas diretas em [.filename]#/dev/gvinum/#. * Os diretórios [.filename]#/dev/gvinum/plex#, e [.filename]#/dev/gvinum/sd# são aqueles que contém device nodes para cada plex e para cada subdisco, respectivamente. Por exemplo, considere o seguinte arquivo de configuração: [.programlisting] .... drive drive1 device /dev/sd1h drive drive2 device /dev/sd2h drive drive3 device /dev/sd3h drive drive4 device /dev/sd4h volume s64 setupstate plex org striped 64k sd length 100m drive drive1 sd length 100m drive drive2 sd length 100m drive drive3 sd length 100m drive drive4 .... Depois de processar este arquivo, o man:gvinum[8] cria a seguinte estrutura em [.filename]#/dev/gvinum#: [.programlisting] .... drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd /dev/vinum/plex: total 0 crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 /dev/vinum/sd: total 0 crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3 .... Embora seja recomendado que os plexes e subdiscos não sejam atribuídos a nomes específicos, as unidades [.filename]#vinum# devem ser nomeadas. Isso possibilita mover uma unidade para um local diferente e ainda reconhecê-la automaticamente. Os nomes dos drives podem ter até 32 caracteres. === Criando sistemas de arquivos Para o sistema os volumes são idênticos aos discos, com uma exceção. Ao contrário das unidades UNIX(R), o [.filename]#vinum# não particiona os volumes, e, portanto, não contêm uma tabela de partições. Isso exigiu modificação em alguns dos utilitários de disco, notavelmente no man:newfs[8], para que ele não tente interpretar a última letra de um nome do volume [.filename]#vinum# como um identificador de partição. Por exemplo, uma unidade de disco pode ter um nome como [.filename]#/dev/ad0a# ou [.filename]#/dev/da2h#. Esses nomes representam a primeira partição ([.filename]#a#) no primeiro (0) disco IDE ([.filename]#ad#) e a oitava partição ([.filename]#h#) no terceiro (2) disco SCSI ([.filename]#da#) respectivamente. Por outro lado, um volume [.filename]#vinum# pode ser chamado de [.filename]#/dev/gvinum/concat#, que não tem relação com o nome da partição. Para criar um sistema de arquivos neste volume, use man:newfs[8]: [source,shell] .... # newfs /dev/gvinum/concat .... [[vinum-config]] == Configurando o [.filename]#vinum# O kernel [.filename]#GENERIC# não suporta o [.filename]#vinum#. É possível compilar um kernel customizado que inclua o suporte estático ao [.filename]#vinum#, mas isso não é recomendado. A maneira padrão de iniciar o [.filename]#vinum# é como um módulo do kernel. O uso do man:kldload[8] não é necessário porque quando o man:gvinum[8] é iniciado, ele verifica se o módulo já foi carregado e, se ele não tiver sido, ele será carregado automaticamente. === Começando O [.filename]#vinum# armazena as informações de configuração nos slices dos discos essencialmente da mesma forma que nos arquivos de configuração. Ao ler a partir do banco de dados de configuração, o [.filename]#vinum# reconhece um número de palavras-chave que não são permitidas nos arquivos de configuração. Por exemplo, uma configuração de disco pode conter o seguinte texto: [.programlisting] .... volume myvol state up volume bigraid state down plex name myvol.p0 state up org concat vol myvol plex name myvol.p1 state up org concat vol myvol plex name myvol.p2 state init org striped 512b vol myvol plex name bigraid.p0 state initializing org raid5 512b vol bigraid sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b .... As diferenças óbvias aqui são a presença de informações explícitas de localização e nomeação, as quais são ambas permitidas mas desencorajadas, e as informações sobre os estados. O [.filename]#vinum# não armazena informações sobre unidades nas informações de configuração. Ele encontra as unidades varrendo as unidades de disco configuradas em busca de partições com um rótulo [.filename]#vinum#. Isso permite que o [.filename]#vinum# identifique as unidades corretamente, mesmo que elas tenham recebido diferentes IDs de unidade UNIX(R). [[vinum-rc-startup]] ==== Inicialização automática O _Gvinum_ apresenta sempre uma inicialização automática assim que o módulo do kernel é carregado, através do man:loader.conf[5]. Para carregar o módulo _Gvinum_ no momento da inicialização, adicione `geom_vinum_load="YES"` ao arquivo [.filename]#/boot/loader.conf#. Quando o [.filename]#vinum# é iniciado com `gvinum start`, o [.filename]#vinum# lê o banco de dados de configuração de uma das unidades [.filename]#vinum#. Em circunstâncias normais, cada unidade contém uma cópia idêntica do banco de dados de configuração, portanto, não importa qual unidade é lida. Após uma falha, no entanto, o [.filename]#vinum# deve determinar qual unidade foi atualizada mais recentemente e ler a configuração desta unidade. Em seguida, atualiza a configuração, se necessário, de unidades progressivamente a partir das mais antigas. [[vinum-root]] == Usando o [.filename]#vinum# para o sistema de arquivos raiz Para uma máquina que tenha sistemas de arquivos totalmente espelhados usando [.filename]#vinum#, é desejável também espelhar o sistema de arquivos raiz. Efetuar esta configuração é menos trivial do que espelhar um sistema de arquivos arbitrário porque: * O sistema de arquivos raiz deve estar disponível muito cedo durante o processo de inicialização, portanto a infraestrutura [.filename]#vinum# já deve estar disponível no momento. * O volume que contém o sistema de arquivos raiz também contém a auto-inicialização do sistema e o kernel. Eles devem ser lidos usando os utilitários nativos do sistema, como o BIOS, que muitas vezes não pode ser instruído sobre os detalhes do [.filename]#vinum#. Nas seções a seguir, o termo "volume raiz" é geralmente usado para descrever o volume [.filename]#vinum# que contém o sistema de arquivos raiz (/). === Iniciando o [.filename]#vinum# cedo o suficiente para o sistema de arquivos raiz O [.filename]#vinum# deve estar disponível no início da inicialização do sistema pois o man:loader[8] deve ser capaz de carregar o módulo do kernel vinum antes de iniciar o kernel. Isto pode ser feito colocando esta linha no [.filename]#/boot/loader.conf#: [.programlisting] .... geom_vinum_load="YES" .... === Tornando um volume raiz baseado em [.filename]#vinum# acessível ao Bootstrap O bootstrap atual do FreeBSD tem apenas 7.5 KB de código e não entende as estruturas internas do [.filename]#vinum#. Isso significa que não é possível analisar os dados de configuração [.filename]#vinum# ou descobrir os elementos de um volume de inicialização. Assim, algumas soluções alternativas são necessárias para fornecer ao código de inicialização a ilusão de que ele está trabalhando com uma partição padrão `a` que contém o sistema de arquivos raiz. Para que isso seja possível, os seguintes requisitos devem ser atendidos para o volume raiz: * O volume raiz não pode ser uma stripe ou `RAID` -5. * O volume raiz não deve conter mais de um subdisco concatenado por plex. Observe que é desejável e possível usar vários plexes, cada um contendo uma réplica do sistema de arquivos raiz. O processo de bootstrap usará apenas uma réplica para localizar o bootstrap e todos os arquivos de inicialização, até que o kernel monte o sistema de arquivos raiz. Cada subdisco dentro desses plexes precisa da sua própria ilusão de partição `a`, para que o respectivo dispositivo seja inicializável. Não é estritamente necessário que cada uma dessas falsas partições `a` estejam localizadas no mesmo deslocamento dentro de seu dispositivo, em comparação com outros dispositivos contendo plexes do volume raiz. No entanto, é provavelmente uma boa ideia criar os volumes [.filename]#vinum# dessa forma para que os dispositivos espelhados resultantes sejam simétricos, para evitar confusão. Para configurar essas partições `a` para cada dispositivo contendo parte do volume raiz, é necessário o seguinte: [.procedure] . A localização, offset desde o início do dispositivo, e o tamanho do subdisco desse dispositivo que faz parte do volume raiz precisam ser examinados, usando o comando: + [source,shell] .... # gvinum l -rv root .... + Os offsets (deslocamentos) e tamanhos do [.filename]#vinum# são medidos em bytes. Eles devem ser divididos por 512 para obter os números de blocos que serão usados pelo `bsdlabel`. . Execute este comando para cada dispositivo que participa do volume raiz: + [source,shell] .... # bsdlabel -e devname .... + No comando acima _devname_ deve ser o nome do disco, como [.filename]#da0# para discos sem uma tabela de slices, ou o nome da slice, como [.filename]#ad0s1#. + Se já existir uma partição `a` no dispositivo a partir de um sistema de arquivos raiz pré-[.filename]#vinum#, ela deve ser renomeada para outra coisa para que permaneça acessível (apenas nesse caso), mas ela não será mais usada por padrão para inicializar o sistema. Um sistema de arquivos raiz atualmente montado não pode ser renomeado, portanto, de forma que o processo ser executado quando o sistema for inicializado a partir de uma mídia "Fixit" ou em um processo de duas etapas em que, em um espelho, o disco que ainda não foi inicializado é manipulado primeiro. + O offset da partição [.filename]#vinum# neste dispositivo (se houver) deve ser adicionado ao deslocamento do respectivo subdisco de volume raiz neste dispositivo. O valor resultante se tornará o valor do `offset` para a nova partição `a`. O valor do `size` para esta partição também pode ser obtido a partir do cálculo acima. O `fstype` deve ser `4.2BSD`. Os valores de `fsize`, `bsize` e `cpg` devem ser escolhidos para corresponder ao sistema de arquivos atual, embora eles sejam relativamente sem importância dentro deste contexto. + Desta forma, uma nova partição `a` será estabelecida sobrepondo a partição [.filename]#vinum# neste dispositivo. O `bsdlabel` só permitirá essa sobreposição se a partição [.filename]#vinum# tiver sido marcada corretamente usando o modo fstype do `vinum`. . Temos agora uma falsa partição `a` em cada dispositivo que possui uma réplica do volume raiz. É altamente recomendável verificar o resultado usando um comando como: + [source,shell] .... # fsck -n /dev/devnamea .... Deve ser lembrado que todos os arquivos contendo informações de controle devem ser relativos ao sistema de arquivos raiz no volume [.filename]#vinum# e que, ao configurarmos um novo volume raiz [.filename]#vinum#, ele pode não corresponder o sistema de arquivos raiz que está atualmente ativo. Então, em particular, o [.filename]#/etc/fstab# e [.filename]#/boot/loader.conf# precisam ser ajustados. Na próxima reinicialização, o bootstrap deve descobrir as informações de controle apropriadas do novo sistema de arquivos raiz baseado no [.filename]#vinum# e agir de acordo. No final do processo de inicialização do kernel, após todos os dispositivos terem sido anunciados, o aviso de destaque que mostra o sucesso desta configuração é uma mensagem como: [source,shell] .... Mounting root from ufs:/dev/gvinum/root .... === Exemplo de uma configuração raiz baseada em [.filename]#vinum# Depois que o volume raiz [.filename]#vinum# foi configurado, a saída de `gvinum l -rv root` pode parecer com: [source,shell] .... ... Subdisk root.p0.s0: Size: 125829120 bytes (120 MB) State: up Plex root.p0 at offset 0 (0 B) Drive disk0 (/dev/da0h) at offset 135680 (132 kB) Subdisk root.p1.s0: Size: 125829120 bytes (120 MB) State: up Plex root.p1 at offset 0 (0 B) Drive disk1 (/dev/da1h) at offset 135680 (132 kB) .... Os valores a serem observados são `135680` para o offset, relativo à partição [.filename]#/dev/da0h#. Isso se traduz em 265 blocos de discos de 512 bytes nos termos do `bsdlabel`. Da mesma forma, o tamanho desse volume raiz é de 245760 blocos de 512 bytes. O [.filename]#/dev/da1h#, contém a segunda réplica deste volume raiz, e possui uma configuração simétrica. O bsdlabel para esses dispositivos pode se parecer com: [source,shell] .... ... 8 partitions: # size offset fstype [fsize bsize bps/cpg] a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*) c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*) h: 71771672 16 vinum # (Cyl. 0*- 4467*) .... Pode-se observar que o parâmetro `size` para a falsa partição `a` corresponde ao valor descrito acima, enquanto o parâmetro `offset` é a soma do deslocamento dentro da partição [.filename]#vinum#`h`, e o offset desta partição dentro do dispositivo ou slice. Esta é uma configuração típica que é necessária para evitar o problema descrito em <>. A partição `a` inteira está completamente dentro da partição `h` que contém todos os dados [.filename]#vinum# para este dispositivo. No exemplo acima, todo o dispositivo é dedicado ao [.filename]#vinum# e não há sobra de partição raiz pré-[.filename]#vinum#. === Soluções de problemas A lista a seguir contém algumas armadilhas e soluções conhecidas. ==== Sistema de bootstrap carrega, mas o sistema não Se por algum motivo o sistema não continuar a inicialização, o bootstrap pode ser interrompido pressionando kbd:[espaço] no aviso de 10 segundos. A variável `vinum.autostart` do loader pode ser examinada digitando `show` e manipulada usando `set` ou `unset`. Se o módulo do kernel [.filename]#vinum# ainda não estava na lista de módulos para carregar automaticamente, digite `load geom_vinum`. Quando estiver pronto, o processo de inicialização pode ser continuado digitando-se `boot -as`, no qual `-as` solicita ao kernel que peça ao sistema de arquivos raiz para montar (`-a`) e fazer com que o processo de inicialização pare no modo single user(`-s`), em que o sistema de arquivos raiz é montado como somente leitura. Dessa forma, mesmo que apenas um plex de um volume multi-plex tenha sido montado, não estaremos arriscando nenhuma inconsistência de dados entre os plexes. No prompt solicitando que um sistema de arquivos raiz seja montado, qualquer dispositivo que contenha um sistema de arquivos raiz válido pode ser inserido. Se o [.filename]#/etc/fstab# estiver configurado corretamente, o padrão deve ser algo como `ufs:/dev/gvinum/root`. Uma opção alternativa típica seria algo como `ufs:da0d`, que poderia ser uma partição hipotética contendo o sistema de arquivos raiz pré-[.filename]#vinum#. Deve-se tomar cuidado se uma das partições alias `a` for inserida aqui, para verificar se ela realmente faz referência aos subdiscos do dispositivo raiz [.filename]#vinum#, porque em uma configuração espelhada, isso apenas montaria uma parte de um dispositivo raiz espelhado. Se este sistema de arquivos tiver que ser montado no modo read-write mais tarde, será necessário remover o(s) outro(s) plex(es) do volume raiz [.filename]#vinum#, já que esses plexes carregariam dados inconsistentes. ==== Apenas o bootstrap primário carrega Se o [.filename]#/boot/loader# falhar ao carregar, mas o bootstrap primário ainda carregar (visível por um único traço na coluna esquerda da tela logo após o processo de boot ser iniciado), uma tentativa pode ser feita para interromper o bootstrap primário pressionando kbd:[espaço]. Isso fará com que o bootstrap pare no link:{handbook}#boot-boot1[estágio dois]. Uma tentativa pode ser feita aqui para inicializar uma partição alternativa, como a partição que contém o sistema de arquivos raiz anterior que foi movido de `a`. [[vinum-root-panic]] ==== Nada carrega e o Bootstrap entra em panic Esta situação acontecerá se o bootstrap tiver sido destruído pela instalação do [.filename]#vinum#. Infelizmente, o [.filename]#vinum# acidentalmente deixa apenas 4 KB no início de sua partição livre antes de começar a escrever suas informações de cabeçalho [.filename]#vinum#. No entanto, o estágio um e dois bootstraps mais o bsdlabel exigem 8 KB. Portanto, se uma partição [.filename]#vinum# tiver sido iniciada no offset 0 dentro de uma slice ou disco que deveria ser inicializável, a configuração do [.filename]#vinum# irá estragar o bootstrap. Da mesma forma, se a situação acima foi recuperada, inicializando de uma mídia "Fixit", e o bootstrap foi reinstalado usando `bsdlabel -B` como descrito em link:{handbook}#boot-boot1[Estágio Um e Estágio Dois], o bootstrap irá estragar o cabeçalho [.filename]#vinum# e o [.filename]#vinum# não encontrará mais seu(s) disco(s). Entretando nenhum dado de configuração real do [.filename]#vinum# e nenhum volume [.filename]#vinum# de dados foi descartado, sendo possível recuperá-los digitando de novo exatamente as mesmas configurações do [.filename]#vinum#, a situação é difícil de corrigir de forma definitiva. Pois será necessário mover toda a partição [.filename]#vinum# em pelo menos 4 KB, para que o cabeçalho [.filename]#vinum# e o bootstrap do sistema não colidam mais.