개념 사전/개발 · 자동화 / 원격 자동화
개념 사전 · 프로그램

Paramiko

파라미코

는 에서 SSH 연결·인증·채널·SFTP 등을 사용하는 라이브러리이다. 가 Transport와 Channel을 감싸며 서버 신뢰 확인··원격 명령 결과 수집을 코드로 구성하게 한다.

밑줄 용어에 마우스를 올리거나, 키보드로 선택하거나, 터치하면 설명을 볼 수 있습니다.

01무엇이고, 어떤 일을 하나

  • 검증된 호스트 키와 자격 증명으로 SSH 연결을 만든다.
  • 원격 명령 채널의 입력·출력·오류·종료 상태를 관리한다.
  • 파일 전송과 연결 수명을 자동화 흐름에 통합한다.

02어떤 순서로 동작하나

  1. 신뢰 자료 준비

    대상과 검증된 , 비밀 공급 경로 및 시간 제한을 준비한다.

  2. 연결·인증

    가 서버 호스트 키를 확인하고 허용된 을 수행한다.

  3. 채널과 출력

    exec_command 등으로 작업 채널을 열어 stdout·stderr를 소비한다. 큰 출력에서는 채널 이 차지 않는 흐름 제어가 필요하다.

  4. 종료·기록

    채널 종료 상태와 결과의 유효성을 기록하고 연결을 닫는다. 응답 유실로 결과가 불명확한 변경은 별도 상태로 남긴다.

03먼저 알아둘 용어와 구성요소

는 서버 키 검증과 인증·채널 생성을 다루는 고수준 객체다.
내부 SSH 전송 연결 위에서 exec_command가 새 채널을 열어 명령을 요청하고 stdin·stdout·stderr를 파일과 비슷한 객체로 반환한다.
load_system_host_keys 또는 지정 파일로 이미 검증한 서버 키를 불러오고 기본 RejectPolicy로 모르는 서버를 거부하는 구성은 접속 대상 확인을 유지한다.
SSH Transport 안의 각 Channel은 독립된 흐름 제어 창을 가진다. 한 채널의 출력을 읽지 않아 창이 차면 원격 측이 그 채널에 더 보내지 못할 수 있다.
recv_ready가 False라는 것은 지금 읽을 데이터가 없다는 뜻이며 채널 종료와 같지 않다. 명령 완료·스트림 종료·남은 출력 소비를 각각 판단한다.
recv_exit_status는 서버가 종료 상태를 제공하지 않으면 -1을 돌려줄 수 있다. 이를 원격 프로그램이 실제로 exit(-1)을 실행했다고 단정하지 않는다.
LEARN THROUGH PRACTICE

장비 자동화의 메뉴·원격 명령·결과 파일을 한 흐름으로 읽기

사용자 입력을 명령으로 바꾸고 결과를 저장하는 자동화 구조에서 실제 성공의 근거를 구별한다.

실습 구성과 전제

  • 흐름도, 장비 설정 메뉴, Jupyter 결과 폴더는 서로 다른 실행 화면이다. 하나의 요청이 모두를 거쳤다고 단정하지 않는다.
  • 실습 장비와 검증한 SSH 호스트 키, 최소 권한 인증 키가 준비된 환경을 가정한다. 아래 코드는 조회 전용으로 재구성한다.

  1. 대상 선택과 접속·작업 함수를 분리한다

    • 흐름도는 메뉴에서 장비 종류와 대상을 선택한 뒤 해당 접속 함수와 작업으로 분기한다. 사용자 입력이 그대로 임의 셸 명령으로 흘러가도록 만들지 않고 허용 작업으로 변환한다.
    • 방식과 대화형 네트워크 CLI는 명령 완료를 판단하는 방법이 다르다. 장비 종류에 따라 채널 또는 의 프롬프트 처리를 선택한다.
    우분투 설정 프로그램 흐름 · 함수 흐름도원본 크기로 보기 ↗
    • 메인 메뉴에서 계정·장비 선택으로 분기하고 Cisco·Rocky·Ubuntu 등 대상 종류가 나뉜다.
    • connect 함수와 설정 백업·invoke_shell 같은 작업 연결이 표현되어 있다.
    확인 기준

    대상·인증·작업·저장 책임을 별도 함수로 나누고, 실패가 어느 단계에서 났는지 결과에 남긴다.

  2. 설정 문장 생성과 장비 적용을 구별한다

    • 메뉴 사진은 입력을 받아 Cisco 설정 문장으로 바꾸고 장비 프롬프트와 완료 메시지를 출력한다. 입력값 검증과 명령 구성의 연결을 보여 준다.
    • 프로그램이 찍은 적용 완료 문자열은 코드에서 정한 표시다. 장비 오류 응답, 실행 후 구성 조회, 실제 할당까지 확인해야 목적한 동작을 입증할 수 있다.
    네트워크 장비 자동 제어 · 파일 위치, 이름, 형식 지정 (2)원본 크기로 보기 ↗
    • 사용자가 DHCP 관련 값을 입력하는 메뉴와 생성된 설정 문장이 보인다.
    • 장비 CLI 프롬프트와 프로그램의 적용 완료 메시지가 이어지지만 실제 클라이언트 임대 결과는 이 화면에 없다.
    확인 기준

    설정 성공 판정을 마지막 print문에 맡기지 않는다. 읽기 전용 사후 조회를 작업별로 정해 기대 상태와 비교한다.

  3. SSH 조회의 출력과 종료 상태를 함께 수집한다

    • 재구성 코드는 사전에 등록된 호스트 키를 확인하고 작은 조회 명령을 실행한다. stdout·stderr·종료 상태를 별도 값으로 보관해 명령 실패를 정상 자료와 구분한다.
    • 큰 출력이나 대화형 세션은 채널 버퍼와 완료 판정 방식이 다르므로 아래 짧은 조회 예시를 그대로 확장하지 않는다. 접속 실패와 실행 후 연결 끊김도 별도 상태로 남겨야 한다.
    from pathlib import Path
import paramiko

client = paramiko.SSHClient()
client.load_system_host_keys()
try:
    client.connect("192.0.2.30", username="labuser",
                   key_filename=str(Path.home() / ".ssh" / "lab_ed25519"),
                   timeout=5, auth_timeout=5, banner_timeout=5)
    stdin, stdout, stderr = client.exec_command("ip -brief address", timeout=10)
    out = stdout.read().decode("utf-8", errors="replace")
    err = stderr.read().decode("utf-8", errors="replace")
    rc = stdout.channel.recv_exit_status()
    print({"returncode": rc, "stdout": out, "stderr": err})
finally:
    client.close()

    준비된 키·를 사용하는 짧은 조회 재구성 예시다. 출력이 큰 작업에는 stdout·stderr를 함께 계속 소비하는 별도 수집기가 필요하다.

    확인 기준

    rc=0은 해당 명령이 보고한 성공이다. 기대한 주소·인터페이스가 출력되는지까지 검증하고, 연결 끊김 뒤 결과가 불명확하면 설정 작업을 무조건 재시도하지 않는다.

  4. 결과 파일은 대상·시각·작업을 식별하게 저장한다

    • Jupyter 화면에는 OS별 폴더 아래 ip_a·ip_r 같은 조회 결과 파일이 보인다. 파일이 만들어진 사실과 파일 내용이 유효한 결과라는 사실은 다르다.
    • 대상 식별자, 수집 시각, 실행 명령, 종료 상태를 함께 저장하면 나중에 주소와 경로를 비교할 때 어떤 시스템의 관찰인지 복원할 수 있다.
    파이썬 SSH 자동화 · Jupyter ip_a (4)원본 크기로 보기 ↗
    • Jupyter의 files/os/rocky/ 경로에 결과 파일들이 보인다.
    • ip_a와 ip_r처럼 조회 작업을 구별하는 파일명이 나열된다.
    확인 기준

    빈 파일·오류 문자열·다른 장비 결과 덮어쓰기를 구분한다. 공개 문서로 옮길 때 자격 정보와 민감 설정은 제외한다.

실습에서 확인한 동작 원리

  • 자동화는 명령 전송만이 아니라 입력 검증·접속 신뢰·실행 결과 판정·근거 저장까지 연결하는 작업이다.
  • CLI 프롬프트나 완료 문구 대신 종료 상태와 사후 조회로 실제 적용 결과를 확인한다.
관련 개념·전체 실습 화면 이어서 읽기 →
동작·명령 참고 문서

04예제로 따라가기

  • 장비 A의 rc=0과 기대 자료, B의 rc=1·stderr, C의 연결 단절은 각각 성공·명령 실패·결과 불명으로 분리한다.
  • 서버 출력이 보다 큰데 읽지 않고 종료만 기다리면 원격 프로그램도 쓰기에서 막혀 서로 기다릴 수 있다.
  • exec_command는 기본적인 원격 명령 채널이며 네트워크 장비의 모드·프롬프트를 자동으로 모두 해석해 주는 함수는 아니다.

05혼동하기 쉬운 점과 확인 기준

  • 개별 read timeout은 전체 작업에 걸리는 최대 시간을 자동 보장하지 않는다. 반복 읽기마다 조금씩 자료가 오면 작업이 계속될 수 있어 전체 마감 시각도 따로 둔다.
  • 모든 출력을 메모리에 누적하면 대상 수와 출력량에 비례해 메모리를 쓴다. 저장·잘림 여부·원래 바이트 수를 구분하고 한도를 넘은 결과를 완전한 백업으로 표시하지 않는다.
  • AutoAddPolicy는 새로운 키를 자동 신뢰하는 정책이지 키 교환 알고리즘 오류를 해결하는 기능이 아니다.

06상세 노트 · 실습 자료

헤더 구조, 설정 예시, 수치 계산과 수업 캡처는 아래 노트에서 이어집니다.

Python·SSH로 운영 작업 자동화하기자동화는 접속에 성공하는 것보다 대상·권한·결과·실패 범위를 관리하는 것이 중요합니다. 조회부터 시작해 반복 가능한 작업으로 발전시킵니다.상세 노트 읽기 →SSH 인증·호스트 키와 연결 진단SSH에서는 서버가 누구인지 확인하는 단계와 사용자가 접속 권한을 증명하는 단계를 구분합니다.상세 노트 읽기 →

공식 문서 · 표준

기초 개념과 동작 설명을 대조한 자료입니다. 제품 버전과 실제 설정에 따른 차이는 본문 및 원문에서 확인하세요.